Reading API Reference Documentation

POST — creates a new payment transaction:

The reference opens with POST /api/v2/payments and the description states: "Creates a new payment transaction." In REST conventions, HTTP methods carry semantic meaning:

• GET → retrieve a resource (read-only, no side effects)
• POST → create a new resource or trigger an action
• PUT → replace an entire resource
• PATCH → partially update a resource
• DELETE → remove a resource

The 201 Created response code (not 200 OK) further confirms this is a creation operation — 201 specifically means "a new resource was created." When reading API reference docs, always check the HTTP method first — it tells you the intent of the operation before you read anything else.

amount, currency, and customer_id are required; the other three are optional:

The request body parameters table clearly marks each field with a Required column:

• amount → Yes (required)
• currency → Yes (required)
• customer_id → Yes (required)
• description → No (optional)
• idempotency_key → No (optional)
• metadata → No (optional)

Reading strategy — the Required column is critical: In API documentation, always check which fields are required vs optional before writing integration code. Sending a request without required fields returns a 400 invalid_request error. Optional fields add useful behaviour (like duplicate prevention via idempotency_key) but the endpoint will work without them.

Tip: The curl example in the docs includes only the required fields plus description and idempotency_key — deliberately omitting metadata to show it is truly optional.

402 means the customer's payment method has insufficient funds:

The error responses table shows: 402 | insufficient_funds | Customer's payment method has insufficient funds.

HTTP 402 Payment Required is a rarely used standard code that becomes meaningful in payment APIs. Here it is used literally — the payment method (card, bank account, or wallet) does not have enough balance.

Distinguishing the error codes in this reference:

• 400 → problem with your request format (your code)
• 401 → authentication failed (your API key)
• 402 → payment method issue (the customer's bank/card)
• 409 → idempotency conflict (duplicate request)
• 422 → valid request, but currency not enabled (account configuration)
• 429 → too many requests (rate limit)

Reading skill: Error response tables map directly to how you write error-handling code in your integration. Each status code requires a different response: 402 means "show the customer a payment failure message," while 401 means "your backend credentials are wrong — don't surface this to the user."

Bearer token in the Authorization header:

The reference states explicitly at the top of the endpoint: "Authentication: Bearer token required in Authorization header. Authorization: Bearer <your_api_key>"

The curl example confirms this pattern:
-H "Authorization: Bearer sk_live_abc123"

Bearer authentication — vocabulary:

• Bearer token → a credential that gives access to whoever "bears" (possesses) it — like a key
• Authorization header → an HTTP request header specifically for credentials
• sk_live_abc123 → the "sk_" prefix commonly denotes a "secret key" (as opposed to "pk_" for public key in payment APIs like Stripe)

Why not query parameters? Passing secrets as query parameters is a security risk — they appear in server access logs, browser history, and proxy logs. Headers are a safer transport for credentials.

The 401 error (unauthorized) is returned if this header is missing or the key is invalid — so authentication is strictly enforced on this endpoint.

idempotency_key prevents duplicate charges on retry:

The parameter table describes it as: "Unique key to prevent duplicate charges on retry."

Idempotency in APIs — why it matters critically in payments:

Imagine this scenario:

1. Your server sends a POST /payments request
2. The network times out — you don't know if the payment was created or not
3. You retry the request

Without idempotency: the customer is charged twice. With idempotency: if the server has already processed a request with this key, it returns the original response instead of creating a new payment. The 409 idempotency_conflict error (in the error table) fires if you try to use a key that already succeeded.

Best practice: Use a meaningful key that ties to your internal order ID — like the example shows: "order_20260601_9182". This way, if you need to retry, you use the same key and the payment system handles deduplication automatically.

Key vocabulary: An operation is idempotent if calling it multiple times produces the same result as calling it once. GET is naturally idempotent; POST (creation) is not — unless you add an idempotency mechanism.