Create a payment

POST 
/payments

Charges a customer's payment method and returns a payment object.

Request

Responses

200

Payment created successfully.

400

Missing or invalid required parameters.

Cause: See error in the response body:

• missing_param: a required field (amount, currency, or customer_id) wasn't provided.
• invalid_param: a field was provided but its value is invalid (for example, currency isn't one of gbp, usd, eur).

Fix: Check message for which field failed, correct the request body, and resend.

Retry: Safe once the request body is corrected. Retrying the same unmodified request will fail again.

401

Missing or invalid API key.

Cause: One of three things; see error in the response body:

• no_api_key: the Authorization header was omitted entirely.
• invalid_api_key: a header was sent but the token isn't a recognized PayFlow key (wrong scheme, malformed, or a test-mode key used against production, or vice versa).
• api_key_expired: the key was valid but has since been rotated or revoked.

Fix: Send Authorization: Bearer <your API key>. For api_key_expired, generate a new key in the Dashboard and update the integration.

Retry: Safe, but will keep failing until a valid, current key for the right environment is supplied.

402

Payment failed (card error).

Cause: See error in the response body:

• card_declined: declined by the issuing bank.
• insufficient_funds: the card has insufficient funds.
• expired_card: the card's expiry date has passed.
• incorrect_cvc: the CVC number is incorrect.
• processing_error: a transient error while processing the card.

Fix: For card_declined, insufficient_funds, and expired_card, ask the customer to use a different payment method or contact their issuer. For incorrect_cvc, ask them to re-enter the card details. For processing_error, retrying later often succeeds.

In the sandbox, trigger each case by using a test customer_id prefix: cus_declined, cus_insufficient, cus_expired, cus_cvc, or cus_processing.

Retry: Not safe to retry unchanged for card_declined, insufficient_funds, expired_card, or incorrect_cvc; the same request will keep failing. Safe to retry processing_error.

409

Duplicate request (idempotency conflict).

Cause: The Idempotency-Key header was reused, but the request body doesn't match the first request that used that key.

Fix: Use a new, unique Idempotency-Key for a genuinely different request. Re-send the original body if you meant to retry the same operation.

Retry: Not safe to retry unchanged; the same conflict will recur. Retrying with the original body succeeds (idempotent replay) instead of erroring.

429

Rate limit exceeded.

Cause: Too many requests were sent from this API key within the current window.

Fix: Slow down request rate and honor the Retry-After header if present. Consider batching or caching reads where possible.

Retry: Safe after waiting out the window; retrying immediately will fail again.

Response Headers

X-RateLimit-Limit

The maximum number of requests allowed per window.

X-RateLimit-Remaining

Requests remaining in the current window.

X-RateLimit-Reset

Unix timestamp (seconds) when the current window resets.

Retry-After

Seconds to wait before retrying.

500

PayFlow server error.

Cause: An unexpected failure on PayFlow's side, not caused by the request.

Fix: Nothing to change in the request. If it persists, contact PayFlow Developer Support with the request ID.

Retry: Safe. Use an idempotency key on write requests so a retry can't create a duplicate if the original actually succeeded.