Idempotency

Partner API uses your idempotency keys — not a separate X-Idempotency-Key header.

Operation	Idempotency field
Withdrawals	reference_id on POST /v1/withdrawals
Payment intents	merchant_reference on POST /v1/payment-intents

Withdrawals

Submitting the same reference_id again returns the original withdrawal with HTTP 200 instead of creating a duplicate.

Call	HTTP	Result
First	201	New withdrawal
Retry (same reference_id)	200	Same withdrawal

Safe retry pattern after network errors:

const referenceId = `payout-${orderId}`;

let withdrawal;
try {
  withdrawal = await client.createWithdrawal({
    amount: "50.00",
    currency: "USDT",
    recipientPhone: "+233501234567",
    mobileNetwork: "MTN",
    referenceId,
  });
} catch (err) {
  if (isRetryable(err)) {
    withdrawal = await client.createWithdrawal({ /* same referenceId */ });
  } else {
    throw err;
  }
}

Generating keys

• Unique per logical payout or checkout within your account
• Deterministic from your domain data when possible, e.g. payout-ORD-9982
• Up to 64 characters

Recommended: UUID or composite key (invoice-{id}).

Payment intents

Same behavior with merchant_reference on POST /v1/payment-intents.

Related

• Withdrawals
• Payment intents