Docs
Search the docs
Find a page in the docs

API reference

Create a payment

Charge a payment method tokenized with the provider, on one of your connections.

POST /v1/payments

Works 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-Key string 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

provider string required
mercadopago or stripe. Must match the connection.
connection_id string required
An active connection in the same environment as the API key (con_…).
amount integer required
Greater than 0, in the currency's minor units.
currency string required
Three-letter ISO code the connection supports, for example ARS.
payment_method object 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).
customer object
email: the payer email, up to 320 characters. Mercado Pago uses it as the payer.
description string
Up to 255 characters.
external_reference string
Your own id for the order, up to 128 characters. You can filter by it.
metadata object
Up to 50 keys of up to 40 characters. Values are strings, integers, or booleans, up to 500 characters.
fx_quote_id string
Charge a converted amount. amount and currency must equal the quote target. See Currency conversion.
provider_options object
Provider-specific options. Today: mercadopago.binary_mode (boolean).

Request

curl -X POST https://api.camelpayment.com/v1/payments \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Idempotency-Key: order-1524" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mercadopago",
    "connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
    "amount": 1500000,
    "currency": "ARS",
    "description": "Order #1524",
    "external_reference": "ORDER-1524",
    "payment_method": {
      "type": "card",
      "token": "ff8080814c11e237014c1ff593b57b4d",
      "installments": 1
    },
    "customer": {
      "email": "buyer@example.com"
    },
    "metadata": {
      "order_id": "1524"
    }
  }'

Response

201
{
  "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

StatusWhen
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.