# Create a payment

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

`POST https://api.camelpayment.com/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**

```bash
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"
    }
  }'
```

**Node.js**

```javascript
const response = await fetch('https://api.camelpayment.com/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAMEL_API_KEY}`,
    'Idempotency-Key': 'order-1524',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "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"
    }
  })
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.camelpayment.com/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['CAMEL_API_KEY']}",
        "Idempotency-Key": "order-1524",
    },
    json={
        "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"
        }
    },
)
data = response.json()
```

## Response

**201**

```json
{
  "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. |
