POST /v1/payments/{uid}/capture
Only when capture_mode is manual and the status is authorized. Partial captures are allowed; the remaining authorization is released automatically.
Path parameters
Headers
Idempotency-Keyrequired | string | A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment. |
Body
amount | integer | Omit to capture the full amount |
Response 200
uid | string | Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum |
reference_id | string | Your own order reference; unique per merchant per environment |
amount | integer | Integer in the minor unit — USD 8900 is $89.00 |
currency | string | |
currency_exponent | integer | Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying |
status | created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded | created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured ·
settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded.
failed and cancelled are terminal: a late success webhook will not flip them back.
|
is_terminal | boolean | Terminal flag computed server-side. Do not infer it from the status enum yourself |
payment_method_type | string | |
card_brand | string | |
card_last4 | string | |
connector_code | string | The provider that finally succeeded (or failed last) |
attempt_count | integer | How many times it cascaded |
three_ds_status | string | |
customer_uid | string | |
authorized_amount | integer | |
captured_amount | integer | |
refunded_amount | integer | |
created_at | string<date-time> | |
available_actions | string[] | What you may do next, computed server-side. Render your buttons from this rather than deriving it. |
Errors
| 409 | The idempotency key was reused with a different body, or the object's state does not allow this operation |
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/capture \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{
"amount": 8900
}' POST /v1/payments/{uid}/void
Cancel an authorization that has not been captured. Use refund for captured payments.
Path parameters
Headers
Idempotency-Keyrequired | string | A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment. |
Response 200
uid | string | Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum |
reference_id | string | Your own order reference; unique per merchant per environment |
amount | integer | Integer in the minor unit — USD 8900 is $89.00 |
currency | string | |
currency_exponent | integer | Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying |
status | created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded | created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured ·
settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded.
failed and cancelled are terminal: a late success webhook will not flip them back.
|
is_terminal | boolean | Terminal flag computed server-side. Do not infer it from the status enum yourself |
payment_method_type | string | |
card_brand | string | |
card_last4 | string | |
connector_code | string | The provider that finally succeeded (or failed last) |
attempt_count | integer | How many times it cascaded |
three_ds_status | string | |
customer_uid | string | |
authorized_amount | integer | |
captured_amount | integer | |
refunded_amount | integer | |
created_at | string<date-time> | |
available_actions | string[] | What you may do next, computed server-side. Render your buttons from this rather than deriving it. |
Errors
| 409 | The idempotency key was reused with a different body, or the object's state does not allow this operation |
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/void \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." POST /v1/payments/{uid}/resume
After the buyer completes 3DS or an off-site step, advance the payment with the resume_token the provider returned.
Path parameters
Headers
Idempotency-Keyrequired | string | A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment. |
Body
resume_tokenrequired | string | |
Response 200
uid | string | Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum |
reference_id | string | Your own order reference; unique per merchant per environment |
amount | integer | Integer in the minor unit — USD 8900 is $89.00 |
currency | string | |
currency_exponent | integer | Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying |
status | created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded | created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured ·
settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded.
failed and cancelled are terminal: a late success webhook will not flip them back.
|
is_terminal | boolean | Terminal flag computed server-side. Do not infer it from the status enum yourself |
payment_method_type | string | |
card_brand | string | |
card_last4 | string | |
connector_code | string | The provider that finally succeeded (or failed last) |
attempt_count | integer | How many times it cascaded |
three_ds_status | string | |
customer_uid | string | |
authorized_amount | integer | |
captured_amount | integer | |
refunded_amount | integer | |
created_at | string<date-time> | |
available_actions | string[] | What you may do next, computed server-side. Render your buttons from this rather than deriving it. |
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/resume \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{
"resume_token": "rt_9d12ac"
}' POST /v1/payments/{uid}/adjust-authorization
Increase or release authorized funds when the order changes. Only some providers support this; the rest return 409.
Path parameters
Headers
Idempotency-Keyrequired | string | A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment. |
Body
amountrequired | integer | The new total, not the difference |
Response 200
uid | string | Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum |
reference_id | string | Your own order reference; unique per merchant per environment |
amount | integer | Integer in the minor unit — USD 8900 is $89.00 |
currency | string | |
currency_exponent | integer | Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying |
status | created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded | created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured ·
settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded.
failed and cancelled are terminal: a late success webhook will not flip them back.
|
is_terminal | boolean | Terminal flag computed server-side. Do not infer it from the status enum yourself |
payment_method_type | string | |
card_brand | string | |
card_last4 | string | |
connector_code | string | The provider that finally succeeded (or failed last) |
attempt_count | integer | How many times it cascaded |
three_ds_status | string | |
customer_uid | string | |
authorized_amount | integer | |
captured_amount | integer | |
refunded_amount | integer | |
created_at | string<date-time> | |
available_actions | string[] | What you may do next, computed server-side. Render your buttons from this rather than deriving it. |
Errors
| 409 | The idempotency key was reused with a different body, or the object's state does not allow this operation |
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/adjust-authorization \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{
"amount": 9900
}'