Payments API
Last updated: 2026-07-17
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 matching PaymentOrder. Keep merchant references unique: a reference that matches more than one payment produces a validation error.
This operation can return INVALID_ARGUMENT for an empty or ambiguous reference
and NOT_FOUND when no matching payment exists.
Simulate a payment status
POST /merchant/api/v1/payment/{id}/simulate
Auth: Secret key
Environment: Non-production only
| Input | Location | Type | Presence |
|---|---|---|---|
id | Path | string (UUID) | Required |
status | Body | string | Required |
providerError | Body | string | Optional |
Supported status values are completed, expired, and declined.
Use simulation to test status and webhook handling in a non-production environment. Do not use it to validate balance or accounting outcomes.
This operation can return INVALID_ARGUMENT for invalid input or a disallowed
transition, NOT_FOUND for an unknown payment, and PERMISSION_DENIED when it
is not available in the current environment.
Related guide: Payment lifecycle.