# Payments

> Charge a tokenized payment method and follow the payment to a final status.

A payment charges a payment method on one of your connections. Your page collects the card with the provider's own tokenization (Mercado Pago's Card Payment Brick or Stripe Elements, for example), and your server sends the token to Camel. Card numbers never reach your server or Camel.

> **Note**
>
> Don't want to build a payment form? Use a [checkout](https://camelpayment.com/docs/checkouts.md) instead. PayPal and Ualá only work through checkouts.

## Create a payment

**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()
```

Camel sends the charge to the provider and answers with the result. Most card payments are final in that response:

**201 Created**

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

Set `external_reference` to your order id: it comes back in every response and webhook, and you can filter payments by it. See all fields in [Create a payment](https://camelpayment.com/docs/api-reference/create-payment.md).

## Payment statuses

| Status | Meaning |
| --- | --- |
| `pending` | Created, waiting for the customer or the provider. |
| `processing` | The provider is still deciding. |
| `requires_action` | The customer must do something, such as 3-D Secure. Details are in `next_action`. |
| `approved` | The money was charged. Fulfil the order. |
| `rejected` | The provider declined it. |
| `cancelled` | Cancelled before it was charged. |
| `failed` | An error, or a chargeback after approval on Mercado Pago. |
| `expired` | Never completed in time. |
| `unknown` | The provider's answer was lost (a timeout). Camel is finding out; don't retry with a new key. |
| `partially_refunded` | Part of the amount was refunded. |
| `refunded` | The whole amount was refunded. |

`rejected`, `cancelled`, `failed`, `expired`, and `refunded` are final. The provider's own status is always in `provider_status`.

## Follow the payment

Payments that aren't final yet change later. Camel learns about it from the provider and sends you a webhook such as `payment.approved`. Older provider events never overwrite a newer status. You can also retrieve the payment at any time:

**cURL**

```bash
curl https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA \
  -H "Authorization: Bearer $CAMEL_API_KEY"
```

**Node.js**

```javascript
const response = await fetch('https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CAMEL_API_KEY}`
  }
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA",
    headers={
        "Authorization": f"Bearer {os.environ['CAMEL_API_KEY']}",
    },
)
data = response.json()
```
