Skip to main content

Best Practices: Ensuring Reliable Payment Integration

This section provides key recommendations to secure, optimize, and ensure the reliability of your payment integration using the Payment API.

Idempotency: Preventing Duplicate Transactions​

Why is Idempotency Important?​

Requests to the Payment API may be accidentally duplicated due to:

  • Network failures, causing a retry.
  • Timeouts, leading the merchant system to resend the same request.
  • User actions, such as clicking multiple times on a "Pay" button.

Without idempotency, these scenarios could result in duplicate payments or refunds.

Best Practices​

  • Use an idempotency key (x-idempotency-key) for all operations that modify transactions (e.g., capture, refund, void).
  • The idempotency key should be unique per operation and generated by your system (e.g., a UUID).
  • If a request fails due to a timeout, retry the same request with the same idempotency key instead of creating a new one.
  • Store idempotency keys for a reasonable duration to prevent duplicate processing in case of failures.

Example: Using Idempotency in a Capture Request​

curl -X POST "https://api.purse-sandbox.com/v2/payments/{{payment-id}}/captures" \\ 
     -H "Authorization: Bearer <access-token>" \\ 
     -H "Content-Type: application/json" \\ 
     -H "x-idempotency-key: 123e4567-e89b-12d3-a456-426614174000" \\ 
     -d '{ 
           "amount": 5000 
         }'

Even if the request is sent multiple times, the API will ensure that the capture is executed only once.

What happens if the same idempotency key is reused?

If you retry a request with the same x-idempotency-key, and the operation was already processed, the API will return a 409 Conflict response.

This response includes the original payment_id and operation_id, allowing you to recover the status of the previous request:

{
    "type": "urn:eu.purse:write-conflict",
    "title": "Idempotency violation",
    "status": 409,
    "instance": "/v2/payments/558f47c6-fd88-4c28-aa2f-5d3d7a44709f/captures",
    "resource_id": "432ccde8-13e8-4c31-a900-a9c40546c12a"
}

Security: Protecting Payment Data​

Best Practices​

  • Always use HTTPS for all API requests to encrypt sensitive data.
  • Use OAuth2 authentication to secure API access and prevent unauthorized requests.
  • Restrict API keys and tokens to specific IPs, users, or actions to limit exposure.
  • Monitor API access logs to detect suspicious behavior and prevent fraud.

Webhook Security​

All webhook events sent by the Payment API are digitally signed to ensure their authenticity.

  • Always verify the signature using the public keys provided by /payment/v2/signing-jwks.
  • Reject any webhook that fails signature validation to prevent spoofed requests.
curl -X GET "https://api.purse-sandbox.com/payment/v2/signing-jwks" \\ 
     -H "Authorization: Bearer <access-token>"

The returned public keys can be used to validate webhook payloads before processing them.

Optimizing API Calls: Performance & Reliability​

Best Practices​

  • Efficient Token Usage → Store and reuse the access token until it expires instead of requesting a new one for each API call.
  • Avoid unnecessary polling → Use webhooks instead to receive real-time updates.
  • Use connection timeouts and retries with exponential backoff for network failures.

Handling Webhooks Efficiently​

Best Practices​

  • Respond to webhook requests within 5 seconds to avoid timeouts.
  • Perform minimal processing inside the webhook handler → Offload heavy tasks to a background queue.
  • Log all received webhooks to debug failures and reprocess missed events if necessary.
  • Validate webhook signatures to prevent unauthorized events from being processed.

Example: Webhook Payload​

{
  "id": "acb149dc-cbc7-4be5-b5c7-4d3f4d40b595",
  "status": "AUTHORIZED",
  "amount": 12000,
  "currency": "EUR",
  "customer": {
    "email": "[email protected]"
  },
  "order": {
    "reference": "123456789"
  }
}

Error Handling & Retry Strategies​

Best Practices​

  • Check all API responses and handle errors appropriately.
  • Implement retries for network failures, but do not retry on client errors (4xx).
  • Log all failed API calls to investigate recurring issues.
  • Use unique request IDs to trace failed transactions and reprocess them if necessary.

Final Recommendations​

Following these best practices will help you:

  • Ensure safe and secure payment processing.
  • Improve API efficiency and reduce unnecessary calls.
  • Prevent duplicate operations and avoid transaction inconsistencies.
  • Handle webhook events effectively without missing critical updates.

Now you're ready to build a robust and reliable payment integration!