Payments API
Last updated: 2026-09-25
Payment operations use a secret key (sk_*). Use them for reconciliation after
creation, redirects, and webhook delivery.
Get a payment by ID
GET /merchant/api/v1/payment/{id}
Auth: Secret key
| Path parameter | Type | Presence |
|---|---|---|
id | string (UUID) | Required |
The response is the merchant-visible PaymentOrder, including any conditional details that apply to the selected flow.
This operation can return INVALID_ARGUMENT for a malformed ID and NOT_FOUND
when the payment is not available to the authenticated merchant.
Get a payment by merchant reference
GET /merchant/api/v1/payment/by-reference/{merchantReference}
Auth: Secret key
| Path parameter | Type | Presence |
|---|---|---|
merchantReference | string | Required |
The response is the current PaymentOrder
associated with the reference in the authenticated realm. If a CANCELLED or
EXPIRED pay-in reference was reused for a permitted new attempt, the lookup
returns that attempt. Use the original payment ID to reconcile an older attempt.
Keep references distinct across pay-ins and payouts. A reference is ambiguous when one current payment cannot be determined, for example when it identifies both directions or multiple older payments without a unique current attempt.
This operation can return INVALID_ARGUMENT for an empty or ambiguous reference
and NOT_FOUND when no matching payment exists.
Related guide: Payment lifecycle.