Skip to main content
POST
/
v0
/
payments
Create Payment
curl --request POST \
  --url https://api.paygentic.io/v0/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "10.50",
  "currency": "USD",
  "idempotencyKey": "order_12345",
  "reference": "Order #12345",
  "successRedirectUrl": "https://example.com/success",
  "savePaymentMethod": false,
  "expiresIn": "P7D",
  "metadata": {
    "orderId": "order_12345"
  }
}
'
{
  "id": "<string>",
  "object": "payment",
  "amount": "<string>",
  "currency": "<string>",
  "status": "pending",
  "createdAt": "2023-11-07T05:31:56Z",
  "paymentUrl": "<string>",
  "customerId": "<string>",
  "idempotencyKey": "<string>",
  "reference": "<string>",
  "metadata": {},
  "lineItems": [
    {
      "description": "<string>",
      "amount": "<string>",
      "quantity": 123
    }
  ],
  "expiresAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

API key authentication

Body

application/json
​
amount
string
required

Payment amount in decimal format (e.g. '10.50'). Minimum 1.00, maximum 5,000.00. Contact support for higher limits.

Pattern: ^\d+(\.\d{1,2})?$
​
currency
enum<string>
required

ISO 4217 currency code.

Available options:
USD,
EUR,
GBP,
AUD
​
merchantId
string

Merchant organization ID. Required when using an API key that is not scoped to a single merchant.

​
customerId
string

Optional customer ID. Must belong to this merchant.

​
idempotencyKey
string

Client-provided key for safe retries. If a payment with the same key already exists, the existing payment is returned.

Maximum string length: 255
​
reference
string

Merchant-defined reference for this payment (e.g. order ID, invoice number).

Maximum string length: 255
​
metadata
object

Arbitrary key-value string pairs to attach to the payment.

​
lineItems
object[]

Optional breakdown of what the customer is being charged for.

Maximum array length: 100
​
successRedirectUrl
string<uri>

URL to redirect the customer to after a successful payment.

​
failureRedirectUrl
string<uri>

URL to redirect the customer to after a failed payment.

​
savePaymentMethod
boolean
default:false

Whether to save the customer's payment method for future use. Defaults to false.

​
expiresIn
string<duration>

ISO 8601 duration for the payment lifetime. Defaults to P30D (30 days). Maximum is P31D (31 days). Examples: PT1H, P1D, P7D, P30D.

Response

Existing payment returned (idempotency match)

​
id
string
required

Unique payment identifier (pay_* prefixed).

​
object
enum<string>
default:payment
required
Available options:
payment
​
amount
string
required

Payment amount in decimal format (e.g. '10.50').

​
currency
string
required

ISO 4217 currency code (e.g. 'USD').

​
status
enum<string>
required

Current status of the payment.

Available options:
pending,
processing,
completed,
expired,
cancelled
​
createdAt
string<date-time>
required

When the payment was created.

​
paymentUrl
string

URL for the customer to complete the payment.

​
customerId
string

Customer ID if provided.

​
idempotencyKey
string

Client-provided idempotency key.

​
reference
string

Merchant-defined reference for this payment.

​
metadata
object

Merchant-provided key-value metadata.

​
lineItems
object[]

Breakdown of what the customer is being charged for.

​
expiresAt
string<date-time>

When the payment expires.