Create a payment

POST

payments

Create a payment

curl --request POST \
  --url https://sandbox-api.paynext.com/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": {
    "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528"
  },
  "metadata": {
    "key": "value"
  },
  "plan": {
    "id": "price_3501fda3-7c64-41d2-9c36-23c4941311f3"
  }
}
'

{
  "amount": 15000,
  "amount_usd": 15000,
  "avs_check": {
    "result": {
      "postal_code": "pass",
      "street_address": "pass"
    }
  },
  "created_at": "2025-05-25T14:30:00Z",
  "currency_code": "AED",
  "customer": {
    "address": {
      "city": "San Francisco",
      "country": "AD",
      "line1": "123 Market Street",
      "line2": "Suite 400",
      "postal_code": "94105",
      "state": "CA"
    },
    "created_at": "2025-05-28T14:00:00Z",
    "email": "[email protected]",
    "external_id": "ext_001",
    "full_name": "Alice Johnson",
    "id": "cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f",
    "metadata": {
      "key": "value"
    },
    "phone": "+1-555-123-4567",
    "updated_at": "2025-05-28T14:05:00Z"
  },
  "cvc_check": {
    "result": {
      "cvc": "pass"
    }
  },
  "id": "pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789",
  "metadata": {
    "key": "value"
  },
  "payment_details": {
    "arn": "123453",
    "auth_code": "334385",
    "network_payment_id": "119676610486528",
    "processor_transaction_id": "pi_3RgN6TJVVBuowJOx0B4fpGWi"
  },
  "payment_method": {
    "details": {
      "bin": "411111",
      "bin_data": {
        "brand": "visa",
        "country": "AD",
        "currency_code": "<string>",
        "description": "Chase Sapphire Preferred",
        "funding": "debit",
        "issuer": "Chase Bank",
        "type": "consumer"
      },
      "exp_month": 12,
      "exp_year": 2028,
      "is_network_tokenized": true,
      "last4": "1111",
      "number": "4111111111111111"
    },
    "type": "CARD",
    "billing_address": {
      "city": "San Francisco",
      "country": "AD",
      "line1": "123 Market Street",
      "line2": "Suite 400",
      "postal_code": "94105",
      "state": "CA"
    }
  },
  "payment_status": "PENDING",
  "payment_token_type": "CARD_PAN",
  "payment_type": "MIT",
  "processor": {
    "description": "Stripe US",
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "processor_merchant_id": "12345678",
    "type": "STRIPE"
  },
  "refunded_amount": 0,
  "statement_descriptor": "MY COMPANY",
  "status_reason": {
    "status": "declined",
    "status_reason": {
      "advice_code": "do_not_try_again",
      "decline_code": "insufficient_funds",
      "message": "<string>"
    }
  },
  "subscription": {
    "created_at": "2025-05-26T10:00:00Z",
    "id": "sub_123e4567-e89b-12d3-a456-426614174000",
    "metadata": {
      "key": "value"
    },
    "next_billing_date": "2025-06-26T12:00:00Z",
    "past_due": {
      "attempt_count": 2,
      "max_attempts_count": 7
    },
    "plan": {
      "id": "price_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "interval": "days",
      "interval_count": 1,
      "name": "Pro Plan",
      "price": {
        "amount": 1999,
        "currency": "AED"
      },
      "trial_interval": "days",
      "trial_interval_count": 14,
      "trial_price": {
        "amount": 1999,
        "currency": "AED"
      },
      "type": "recurring"
    },
    "status": "trial",
    "updated_at": "2025-05-27T10:00:00Z"
  },
  "three_d_secure": {
    "authentication_flow": "<string>",
    "electronic_commerce_indicator": "<string>",
    "liability_shift": true,
    "result": "<string>",
    "result_reason": "<string>",
    "transaction_id": "<string>",
    "version": "<string>"
  },
  "updated_at": "2025-05-26T10:15:00Z"
}

Authorizations

Authorization

string

header

required

Authentication header of the form api key, where api key is your organization api key.

Headers

X-API-Version

enum<string>

Specifies the version of the API to use

Available options:

1.0.0

Body

application/json

Create payment

customer

object

Customer information for the payment

Show child attributes

metadata

object

Custom metadata associated with the payment A dictionary of key-value pairs.

Show child attributes

Example:

{ "key": "value" }

plan

object

Plan information for the payment

Show child attributes

Response

amount

integer

Payment amount in the specified currency (e.g., cents)

Example:

15000

amount_usd

integer

Payment amount converted to USD (e.g., cents)

Example:

15000

avs_check

object

Avs check

Show child attributes

created_at

string

The date and time at which the payment was created in UTC format.

Example:

"2025-05-25T14:30:00Z"

currency_code

enum<string>

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

Available options:

AED,

AFN,

ALL,

AMD,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BZD,

CAD,

CDF,

CHF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HTG,

HUF,

IDR,

ILS,

IMP,

INR,

IQD,

IRR,

ISK,

JEP,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SLE,

SOS,

SRD,

SSP,

STD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

BOV,

COU,

CHE,

CHW,

MXV,

UGX,

VES,

VND,

VUV,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

USD

customer

object

Show child attributes

cvc_check

object

CVC check

Show child attributes

string

Unique identifier of the payment.

Example:

"pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789"

metadata

object

Custom metadata associated with the payment A dictionary of key-value pairs.

Show child attributes

Example:

{ "key": "value" }

payment_details

object

Transaction details related to payment

Show child attributes

payment_method

Card API Schema · object

Show child attributes

payment_status

enum<string>

Current status of the payment

Available options:

PENDING,

FAILED,

AUTHORIZED,

SETTLING,

SETTLED,

DECLINED,

BLOCKED,

CANCELLED

payment_token_type

enum<string>

Type of card token used, if applicable

Available options:

CARD_PAN,

NETWORK_TOKEN,

PROCESSOR_TOKEN

payment_type

enum<string>

Indicates whether the transaction was merchant-initiated (MIT) or customer-initiated (CIT).

Available options:

MIT,

CIT

processor

object

Show child attributes

refunded_amount

integer

Amount refunded from the original payment

Example:

0

statement_descriptor

string

Statement descriptor shown on the customer's bank statement

Example:

"MY COMPANY"

status_reason

object

Reason of payment status

Show child attributes

subscription

object

Show child attributes

three_d_secure

object

Information about 3DS

Show child attributes

updated_at

string

The date and time of the last payment update in UTC format.

Example:

"2025-05-26T10:15:00Z"

Refund a paymentRefund a payment

⌘I

Create a payment

curl --request POST \
  --url https://sandbox-api.paynext.com/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": {
    "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528"
  },
  "metadata": {
    "key": "value"
  },
  "plan": {
    "id": "price_3501fda3-7c64-41d2-9c36-23c4941311f3"
  }
}
'

{
  "amount": 15000,
  "amount_usd": 15000,
  "avs_check": {
    "result": {
      "postal_code": "pass",
      "street_address": "pass"
    }
  },
  "created_at": "2025-05-25T14:30:00Z",
  "currency_code": "AED",
  "customer": {
    "address": {
      "city": "San Francisco",
      "country": "AD",
      "line1": "123 Market Street",
      "line2": "Suite 400",
      "postal_code": "94105",
      "state": "CA"
    },
    "created_at": "2025-05-28T14:00:00Z",
    "email": "[email protected]",
    "external_id": "ext_001",
    "full_name": "Alice Johnson",
    "id": "cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f",
    "metadata": {
      "key": "value"
    },
    "phone": "+1-555-123-4567",
    "updated_at": "2025-05-28T14:05:00Z"
  },
  "cvc_check": {
    "result": {
      "cvc": "pass"
    }
  },
  "id": "pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789",
  "metadata": {
    "key": "value"
  },
  "payment_details": {
    "arn": "123453",
    "auth_code": "334385",
    "network_payment_id": "119676610486528",
    "processor_transaction_id": "pi_3RgN6TJVVBuowJOx0B4fpGWi"
  },
  "payment_method": {
    "details": {
      "bin": "411111",
      "bin_data": {
        "brand": "visa",
        "country": "AD",
        "currency_code": "<string>",
        "description": "Chase Sapphire Preferred",
        "funding": "debit",
        "issuer": "Chase Bank",
        "type": "consumer"
      },
      "exp_month": 12,
      "exp_year": 2028,
      "is_network_tokenized": true,
      "last4": "1111",
      "number": "4111111111111111"
    },
    "type": "CARD",
    "billing_address": {
      "city": "San Francisco",
      "country": "AD",
      "line1": "123 Market Street",
      "line2": "Suite 400",
      "postal_code": "94105",
      "state": "CA"
    }
  },
  "payment_status": "PENDING",
  "payment_token_type": "CARD_PAN",
  "payment_type": "MIT",
  "processor": {
    "description": "Stripe US",
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "processor_merchant_id": "12345678",
    "type": "STRIPE"
  },
  "refunded_amount": 0,
  "statement_descriptor": "MY COMPANY",
  "status_reason": {
    "status": "declined",
    "status_reason": {
      "advice_code": "do_not_try_again",
      "decline_code": "insufficient_funds",
      "message": "<string>"
    }
  },
  "subscription": {
    "created_at": "2025-05-26T10:00:00Z",
    "id": "sub_123e4567-e89b-12d3-a456-426614174000",
    "metadata": {
      "key": "value"
    },
    "next_billing_date": "2025-06-26T12:00:00Z",
    "past_due": {
      "attempt_count": 2,
      "max_attempts_count": 7
    },
    "plan": {
      "id": "price_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "interval": "days",
      "interval_count": 1,
      "name": "Pro Plan",
      "price": {
        "amount": 1999,
        "currency": "AED"
      },
      "trial_interval": "days",
      "trial_interval_count": 14,
      "trial_price": {
        "amount": 1999,
        "currency": "AED"
      },
      "type": "recurring"
    },
    "status": "trial",
    "updated_at": "2025-05-27T10:00:00Z"
  },
  "three_d_secure": {
    "authentication_flow": "<string>",
    "electronic_commerce_indicator": "<string>",
    "liability_shift": true,
    "result": "<string>",
    "result_reason": "<string>",
    "transaction_id": "<string>",
    "version": "<string>"
  },
  "updated_at": "2025-05-26T10:15:00Z"
}

Introduction

API Reference

Authorizations

Headers

Body

Response