## Create a Payment

```http
POST https://api.example.com/v1/payments
```

Creates a new payment transaction.

## Retrieve a Payment

```http
GET https://api.example.com/v1/payments/{payment_id}
```

Retrieves the details of a payment that has been previously created.

### Parameters

<ParamField path="amount" type="integer" required>
  Payment amount in the smallest currency unit (e.g., cents for USD). 
  Must be a positive integer.
  
  Minimum: `50` ($0.50)
  Maximum: `99999999` ($999,999.99)
</ParamField>

<ParamField path="currency" type="string" required>
  Three-letter ISO currency code in lowercase.
  
  Supported currencies: `usd`, `eur`, `gbp`, `jpy`, [see full list](/docs/currencies)
</ParamField>

<ParamField path="capture_method" type="string" default="automatic">
  When to capture the payment.
  
  - `automatic` - Capture immediately (default)
  - `manual` - Authorize now, capture later
  
  Use `manual` for pre-authorization or delayed capture workflows.
</ParamField>

<ParamField path="metadata" type="object">
  Set of key-value pairs for storing additional information.
  
  Maximum 50 keys, each key up to 40 characters, each value up to 500 characters.
  
  ```json
  {
    "order_id": "12345",
    "customer_name": "Jane Doe"
  }
  ```
</ParamField>

## Example Request

<CodeGroup>
```bash cURL
curl https://api.example.com/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "usd",
    "payment_method": "pm_card_visa",
    "description": "Order #12345"
  }'
```

```javascript Node.js
const payment = await client.payments.create({
  amount: 2000,
  currency: 'usd',
  payment_method: 'pm_card_visa',
  description: 'Order #12345'
});
```

```python Python
payment = client.payments.create(
  amount=2000,
  currency='usd',
  payment_method='pm_card_visa',
  description='Order #12345'
)
```
</CodeGroup>

## Response

Returns a Payment object if successful.

<ResponseField name="id" type="string">
  Unique identifier for the payment.
  
  Format: `pay_` followed by 24 alphanumeric characters
</ResponseField>

<ResponseField name="status" type="string">
  Current payment status.
  
  Possible values:
  - `pending` - Payment is being processed
  - `succeeded` - Payment completed successfully
  - `failed` - Payment failed (see `error` field)
  - `canceled` - Payment was canceled
</ResponseField>

<ResponseField name="amount" type="integer">
  Amount charged in the smallest currency unit.
</ResponseField>

<ResponseField name="created" type="timestamp">
  Unix timestamp when the payment was created.
</ResponseField>

<ResponseField name="metadata" type="object" optional>
  Additional information attached to the payment.
  
  Only present if metadata was provided in the request.
</ResponseField>

### Example Response

```json
{
  "id": "pay_1A2B3C4D5E6F7G8H",
  "object": "payment",
  "status": "succeeded",
  "amount": 2000,
  "currency": "usd",
  "created": 1640000000,
  "payment_method": "pm_card_visa",
  "description": "Order #12345"
}
```

## Errors

<ResponseField name="error" type="object">
  Present when the request fails.
</ResponseField>

### Common Errors

| Status | Error Code | Description |
|--------|------------|-------------|
| 400 | `invalid_request` | Missing required parameter or invalid value |
| 401 | `invalid_api_key` | Authentication failed - check your API key |
| 402 | `card_declined` | The card was declined by the issuer |
| 404 | `resource_not_found` | The payment ID doesn't exist |
| 429 | `rate_limit_exceeded` | Too many requests - slow down |
| 500 | `internal_error` | Something went wrong on our end |

### Example Error Response

```json
{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": "payment_method"
  }
}
```