June 2024 Recap

Welcome to the June 2024 changelog! This month, we’ve made several important updates to enhance your experience with our API. These include new instructions for provider method mapping, support for partial refunds, updates to agreement participants in the KYC API, and the ability to update payer information. Let's dive into the details

Welcome to the June 2024 changelog! This month, we’ve made several important updates to enhance your experience with our API. These include new instructions for provider method mapping, support for partial refunds, updates to agreement participants in the KYC API, and the ability to update payer information. Let's dive into the details

1. New Instructions for Provider Method Mapping

We've introduced new, detailed instructions for provider method mapping. These instructions are designed to help you understand which provider and method should be used when creating a payment.

You can find the complete documentation here.

Key Points:

  • Purpose: Helps in identifying the correct provider and method for payments.
  • Benefit: Simplifies the process of integrating the initiation of payments by providing clear mapping guidelines.

2. Support for Partial Refunds

Our existing refund endpoint now supports partial refunds. This means you can refund a smaller amount than the full payment. When performing a partial refund, you must provide an updated order_items list to ensure the distribution of funds remains accurate.

Endpoint:

POST api/v1/payment_orders/{payment_order_id}/payments/{payment_id}/refund

Payload Changes:

PropertyTypeDescriptionOptional
order_itemsarray of objectsUpdated list of items with their respective amounts and details.No when using partial refunds, empty for full refund

order_items Object:

FieldTypeDescriptionOptional
amountintegerCost of the item in minor units of currency (e.g., öre for SEK).No
liquidity_account_idstring, nullLiquidity Account ID (UUID4).Yes, but if no then merchant_id
merchant_idstring, nullMerchant ID (UUID4).Yes, bu tif no, then liquidity_account_id
metadataobjectContains item-specific metadata.No
metadata.namestringItem name.No
metadata.tagsarray of stringsTags used for routing funds.Yes
vat_ratenumberVAT rate of the item.No

Partial refunds are supported for the following payment methods:

  • Cards
  • Swish
  • Autogiro

For more information, visit the refund endpoint documentation

3. Update Agreement Participant in KYC API

You can now update an agreement participant's details using our KYC API. This is useful when participant information changes or needs correction. Note that updating a participant will require all parties to re-sign the agreement.

Endpoint:

PUT api/v1/agreements/{agreement_id}/participants/{participant_id}

Path Parameters:

ParameterTypeDescription
agreement_idstringAgreement ID (required).
participant_idstringParticipant ID (required).

Body Parameters:

FieldTypeDescription
participantobjectContains participant details (required).
participant.countrystringTwo-letter ISO 3166-2 country code.
participant.delivery_channelstringMethod for receiving the agreement.
participant.delivery_statusstringDelivery status.
participant.emailstringEmail address.
participant.idstringParticipant ID.
participant.identifierstringUnique identifier, e.g., personal ID number.
participant.namestringParticipant name.
participant.organizerbooleanWhether the participant is the organizer.
participant.phone_numberstringPhone number.
participant.sign_methodstringMethod for signing the agreement.
participant.sign_statestringCurrent signing state.
participant.sign_state_updated_atdate-timeTimestamp of last state update.
participant.signatorybooleanWhether the participant is a signatory.
participant.titlestringParticipant title.
participant.two_step_authentication_methodstringMethod for two-step authentication.

Headers:

HeaderTypeDescription
tenant_idstringTenant ID (required)

You can find more details here.

4. Updating Payer Information

In response to transaction monitoring alerts, additional payer information can now be sent to Ping via the API. This includes comprehensive details about the payer, enhancing the monitoring and verification processes.

Endpoint:

PUT /payments/api/v1/payments/{payment_id

payer Object:

FieldTypeDescription
addressobjectAddress of the payer.
address.citystring, nullCity.
address.countrystring, nullTwo-letter ISO 3166-2 country code.
address.countystring, nullCounty.
address.postal_codestring, nullPostal code.
address.streetstring, nullStreet address.
emailstring, nullEmail address of the payer.
identityobject, nullIdentification details of the payer.
identity.countrystringTwo-letter ISO 3166-2 country code.
identity.identifierstring, nullUnique identifier (e.g., personal ID number).
identity.typestringEntity type (organization or person).
ip_addressstring, nullIP address of the payer.
namestring, nullName of the payer.
phone_numberstring, nullPhone number of the payer.
source_of_fundsarray of stringsSources of funds for the payment.

This update allows for more detailed information to be provided, which is essential for compliance and fraud prevention.

For further information, please refer to the update payment documentation.