API reference
Create a payment
Charge a payment method tokenized with the provider, on one of your connections.
POST
/v1/paymentsWorks with providers that accept direct payments: Mercado Pago and Stripe. PayPal and Ualá connections only take checkouts.
Production keys get 402 while the account has a past-due Camel invoice.
Headers
Idempotency-Keystring required- A unique key for this operation, up to 255 characters. Retrying with the same key and body returns the original response. See Idempotency.
Body parameters
providerstring required- mercadopago or stripe. Must match the connection.
connection_idstring required- An active connection in the same environment as the API key (con_…).
amountinteger required- Greater than 0, in the currency's minor units.
currencystring required- Three-letter ISO code the connection supports, for example ARS.
payment_methodobject required- type (required, up to 32 characters, for example card), token (required, the provider token, up to 512 characters), installments (1–48), provider_method_id (for example visa on Mercado Pago).
customerobject- email: the payer email, up to 320 characters. Mercado Pago uses it as the payer.
descriptionstring- Up to 255 characters.
external_referencestring- Your own id for the order, up to 128 characters. You can filter by it.
metadataobject- Up to 50 keys of up to 40 characters. Values are strings, integers, or booleans, up to 500 characters.
fx_quote_idstring- Charge a converted amount. amount and currency must equal the quote target. See Currency conversion.
provider_optionsobject- Provider-specific options. Today: mercadopago.binary_mode (boolean).
Request
Response
{
"id": "pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA",
"object": "payment",
"provider": "mercadopago",
"connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
"provider_payment_id": "1342345678",
"amount": 1500000,
"currency": "ARS",
"conversion": null,
"usd_amount": 971,
"status": "approved",
"provider_status": "approved",
"description": "Order #1524",
"external_reference": "ORDER-1524",
"payment_method": {
"type": "card",
"brand": "visa",
"last4": "4242"
},
"failure": null,
"metadata": {
"order_id": "1524"
},
"next_action": null,
"created_at": "2026-11-12T15:04:05Z",
"updated_at": "2026-11-12T15:04:07Z"
}Errors
| Status | When |
|---|---|
202 | The provider did not give a definitive answer (a timeout, for example). The resource is returned with status unknown and Camel reconciles it. Do not create it again. |
400 | The Idempotency-Key header is empty. |
401 | The API key is missing, malformed, or revoked. |
402 | Production only: the account has a past-due Camel invoice. |
404 | The connection or the FX quote does not exist in this environment. |
409 | The Idempotency-Key was used with a different body, or the first request is still running. |
409 | The FX quote has expired. |
422 | The body is invalid, the currency is not supported by the connection, the provider only takes checkouts, or the amount does not match the quote. |
429 | Too many requests. Wait for Retry-After seconds. |
502 | The provider returned an error. The body is still the resource, with status failed. |