🔄Idempotency

Idempotency ensures that duplicate requests do not result in unintended side effects, such as double payouts or reconciliation errors.

Benefits of Idempotency

shield-check

Prevent Duplicate Charges

Retry failed requests safely without charging customers multiple times

wifi

Network Resilience

Recover from timeout errors and network interruptions without data loss

list-check

Simplify Reconciliation

Maintain consistent ledger state across retries and system failures

globe

Multi-Currency Safety

Ensure atomic operations across currency conversions and cross-border transfers

Reference Fields by Endpoint

Endpoint	Reference Field	Description
Create Payment Link	`reference` (optional)	Custom identifier for the payment link
SendR Payout	`reference`	Required unique identifier for cross-border disbursement
Payout Fund Transfer	`reference`	Required unique identifier for the payout
Bulk Fund Transfer	`tenantReference`	Required unique reference for each recipient in the batch

info-circle
Reference Requirements

Unique across your account

Alphanumeric with hyphens/underscores

Max 50 characters

Case-sensitive

Immutable once created

Example

const response = await fetch(
  'https://api.sandbox.leatherback.co/v1/payout/Disbursement/Payout/FundTransfer',
  {
    method: 'POST',
    headers: {
      'X-Api': 'sk_test_YOUR_SECRET_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reference: 'payout_ORDER123_20240115', // Your unique reference
      currencyCode: 'USD',
      amount: 50000
      // ... other fields
    })
  }
);

First request:

{
  "status": true,
  "data": {
    "reference": "payout_ORDER123_20240115",
    "transactionId": "TXN789012",
    "status": "completed"
  }
}

Retry with same reference:

{
  "status": true,
  "data": {
    "reference": "payout_ORDER123_20240115",
    "transactionId": "TXN789012",
    "status": "completed"
  }
}

Duplicate Reference Error

If the reference exists in a conflicting state, you'll receive:

{
  "status": false,
  "code": "DUPLICATE_REFERENCE",
  "message": "A transaction with reference 'payout_ORDER123_20240115' already exists",
  "errors": []
}

When you receive this error:

Do not generate a new reference
Query the transaction status using Get Transaction Status
Use the existing result if completed, or retry with a new reference if failed