Skip to main content
POST
/
v2
/
payment-orders
Create a payment order (v2)
curl --request POST \
  --url http://localhost:3156/v2/payment-orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-merchant-id: <api-key>' \
  --data '
{
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+525512345678"
  },
  "paymentMethod": {
    "type": "card",
    "cardDetails": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "25",
      "cvc": "123"
    },
    "persist": false
  },
  "amount": 250,
  "currency": "MXN",
  "description": "Payment for order #12345",
  "externalId": "ORDER-12345",
  "billingAddress": {
    "address": "Av. Reforma 123",
    "city": "Mexico City",
    "state": "CDMX",
    "postalCode": "01000",
    "country": "MX"
  }
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalMerchantReference": "ORDER-12345",
  "amount": 250,
  "orderNumber": "C25123101",
  "currency": "MXN",
  "status": "PENDING",
  "description": "Payment for order #12345",
  "createdAt": "2025-10-20T10:00:00.000Z",
  "paymentMethod": {
    "type": "card",
    "cardDetails": {
      "last4": "1111",
      "brand": "VISA",
      "country": "US",
      "expiryMonth": "12",
      "expiryYear": "25"
    }
  },
  "customer": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+525512345678"
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication (required)

​
x-merchant-id
string
header
required

Merchant ID for identifying the merchant (required)

Body

application/json
​
customer
object
required
​
paymentMethod
object
required
​
amount
number
required

Payment amount (must be positive)

Required range: x > 0
Example:

100.5

​
currency
string
required

Three-letter currency code (ISO 4217)

Required string length: 3
Example:

"MXN"

​
externalId
string
required

External reference ID from merchant system (required)

Minimum string length: 1
Example:

"ORDER-12345"

​
description
string

Payment order description

Example:

"Payment for order #12345"

​
billingAddress
object

Billing address (required when paymentMethod.type is 'card')

​
deviceInformation
object

Device and browser information for fraud detection

Response

Payment order created successfully

​
id
string<uuid>
required

Payment order unique identifier

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
amount
number
required

Payment amount

Example:

250

​
currency
string
required

Currency code

Example:

"MXN"

​
status
enum<string>
required

Payment order status

Available options:
PENDING,
PROCESSING,
AUTHORIZED,
PARTIALLY_AUTHORIZED,
ACTION_REQUIRED,
COMPLETED,
PARTIALLY_PAID,
CANCELLATION_REQUESTED,
CANCELLED,
FAILED,
REFUND_PROCESSING,
PARTIALLY_REFUNDED,
REFUNDED
Example:

"PENDING"

​
externalMerchantReference
string

External merchant reference ID

Example:

"ORDER-12345"

​
orderNumber
string

System-generated order number

Example:

"C25123101"

​
description
string

Payment order description

Example:

"Payment for order #12345"

​
createdAt
string<date-time>

Creation timestamp

Example:

"2025-10-20T10:00:00.000Z"

​
paymentMethod
object
​
customer
object
​
payerAuthentication
object

3DS authentication details (when required)