May 2024 Recap

1. New endpoint for uploading documents for a payment

This endpoint allows you to upload documents (e.g., invoices or sales agreements) to a specific payment order. This is particularly useful for addressing transaction monitoring alerts by providing evidence of the transaction's purpose.

Endpoint:

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

Headers:

tenant_id: <Your Tenant ID>

Path Parameters:

payment_order_id: <Payment Order ID>
payment_id: <Payment ID>

Payload:

[
  {
    "content": "<Base64 encoded document data>",
    "mime_type": "application/pdf", 
    "name": "invoice.pdf",
    "type": "invoice" 
  }
]

Response:

• 204 No Content: All documents were successfully uploaded.
• 207 Multi-Status: Some documents failed to upload. The response body will include details:

{
  "failures": ["document2.pdf"],
  "success": ["document1.pdf"]
}

2. New endpoint: get payments with filtering

This endpoint retrieves a list of payments. You can filter the results by date range, status, payment method, provider, and refund status.

Endpoint:

GET /payments/api/v1/payments

Headers:

tenant_id: <Your Tenant ID>

Query Parameters:

• from_initiated_date_time (date-time): Filter payments initiated after this date and time (ISO 8601 format).
• to_initiated_date_time (date-time): Filter payments initiated before this date and time (ISO 8601 format).
• status (string): Filter by payment status (e.g., COMPLETED, PENDING, CRASHED).
• method (string): Filter by payment method (e.g., card, e_commerce).
• provider (string): Filter by payment provider (e.g., swish, payment_id).
• is_refund_requested (boolean): Filter payments with or without refund requests.
• limit (integer): Limit the number of results per page (default: 50).
• starting_after (string): Pagination cursor for fetching the next page of results.
• ending_before (string): Pagination cursor for fetching the previous page of results.

Response:

{
  "_links": {
    "current": { "href": "..." },
    "first": { "href": "..." },
    "next": { "href": "..." },
    "previous": { "href": "..." },
    "ending_before_including": { "href": "..."}
  },
  "data": [
    {
      "currency": "EUR",
      "id": "...",
      // ... payment details
    },
    // ... more payments
  ]
}

Explanation of Response:

• _links: Contains links for pagination.

  • current: Link to the current page.
  • first: Link to the first page.
  • next: Link to the next page (if available).
  • previous: Link to the previous page (if available).
  • ending_before_including: This provides the endpoint used to get payments that initiated before a specific time and can be used as ending_before to page back

• data: Array of payment objects, each containing details about a payment.

3. New endpoint for uploading documents to merchant

Use this endpoint to upload documents related to a merchant during a transaction monitoring alert or to perform necessarily KYC information requirements.

Endpoint:

POST /payments/api/v1/merchants/{merchant_id}/documents

Headers:

tenant_id: <Your Tenant ID>

Path Parameters:

merchant_id: <Merchant ID>

Payload:

{
  "content": "<Base64 encoded document data>",
  "mime_type": "image/png", 
  "name": "registration_certificate.png",
  "type": "registration_certificate" 
}

Response:

• 204 No Content: The document was successfully uploaded.