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
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:
| Property | Type | Description | Optional |
|---|---|---|---|
| order_items | array of objects | Updated list of items with their respective amounts and details. | No when using partial refunds, empty for full refund |
order_items Object:
order_items Object:| Field | Type | Description | Optional |
|---|---|---|---|
| amount | integer | Cost of the item in minor units of currency (e.g., öre for SEK). | No |
| liquidity_account_id | string, null | Liquidity Account ID (UUID4). | Yes, but if no then merchant_id |
| merchant_id | string, null | Merchant ID (UUID4). | Yes, bu tif no, then liquidity_account_id |
| metadata | object | Contains item-specific metadata. | No |
| metadata.name | string | Item name. | No |
| metadata.tags | array of strings | Tags used for routing funds. | Yes |
| vat_rate | number | VAT 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:
| Parameter | Type | Description |
|---|---|---|
| agreement_id | string | Agreement ID (required). |
| participant_id | string | Participant ID (required). |
Body Parameters:
| Field | Type | Description |
|---|---|---|
| participant | object | Contains participant details (required). |
| participant.country | string | Two-letter ISO 3166-2 country code. |
| participant.delivery_channel | string | Method for receiving the agreement. |
| participant.delivery_status | string | Delivery status. |
| participant.email | string | Email address. |
| participant.id | string | Participant ID. |
| participant.identifier | string | Unique identifier, e.g., personal ID number. |
| participant.name | string | Participant name. |
| participant.organizer | boolean | Whether the participant is the organizer. |
| participant.phone_number | string | Phone number. |
| participant.sign_method | string | Method for signing the agreement. |
| participant.sign_state | string | Current signing state. |
| participant.sign_state_updated_at | date-time | Timestamp of last state update. |
| participant.signatory | boolean | Whether the participant is a signatory. |
| participant.title | string | Participant title. |
| participant.two_step_authentication_method | string | Method for two-step authentication. |
Headers:
| Header | Type | Description |
|---|---|---|
| tenant_id | string | Tenant 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:
payer Object:| Field | Type | Description |
|---|---|---|
| address | object | Address of the payer. |
| address.city | string, null | City. |
| address.country | string, null | Two-letter ISO 3166-2 country code. |
| address.county | string, null | County. |
| address.postal_code | string, null | Postal code. |
| address.street | string, null | Street address. |
| string, null | Email address of the payer. | |
| identity | object, null | Identification details of the payer. |
| identity.country | string | Two-letter ISO 3166-2 country code. |
| identity.identifier | string, null | Unique identifier (e.g., personal ID number). |
| identity.type | string | Entity type (organization or person). |
| ip_address | string, null | IP address of the payer. |
| name | string, null | Name of the payer. |
| phone_number | string, null | Phone number of the payer. |
| source_of_funds | array of strings | Sources 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.