---
title: "Create a payment order"
method: POST
path: "/open-api/v3/acquiring/payments"
tags: ["Payments"]
---

# Create a payment order

`POST /open-api/v3/acquiring/payments`

Create a payment order.
Integration Methods:
1. API-ONLY Integration
   1.1 Card Payments
       1.1.1 Hosted Mode (Supports full hosted/embedded mode)
       1.1.2 Server-to-Server Mode
2. Checkout Page Integration (Supports full hosted mode, embedded mode not supported yet)
   2.1 Create checkout session (Customers choose payment method themselves)
   2.2 Pre-selected payment method

Payment Method Value and ID Mapping:
- CARD:(100002)
- CRYPTO_CARD:(100003)
- USDC:(100007)
- USDT:(100008)

## Request body

- AcquiringPaymentCreateReqDTO
  - `merchantTradeNo` string, required — Merchant-generated order number, globally unique/idempotent
  - `amount` string, required — Order amount in string format, up to 6 decimal places
  - `currency` string, required — Order currency
  - `country` string, required — Order country
  - `paymentDetail` PaymentDetailReqDTO — Payment details
    - `paymentMethod` string — Payment method enums CARD,CRYPTO_CARD,USDC,USDT
    - `paymentMethodId` string — Payment method Id, if both paymentMethod and paymentMethodId are provided, paymentMethodId takes precedence
    - `integrationMode` string — Integration mode, direct/redirect, default is redirect
    - `displayMode` string — Display mode, CHECKOUT, IFRAME(EMBEDDED)
    - `threeDS` ThreeDomainSecureReqDTO — 3DS configuration parameters
      - `enable` boolean — Whether to enable 3DS
  - `callbackUrls` CallbackUrlReqDTO — Callback notification URLs
    - `success` string — URL to redirect after successful payment
    - `fail` string — URL to redirect after failed payment
    - `notify` string — Custom notification URL
  - `returnUrls` ReturnUrlDTO — return URLs
    - `successUrl` string — URL to redirect after successful payment
    - `failUrl` string — URL to redirect after failed payment
  - `card` CardReqDTO — Card information
    - `firstName` string — First name
    - `lastName` string — Last name
    - `pan` string — Card number
    - `expireMonth` string — Expiration month
    - `expireYear` string — Expiration year
    - `cvv` string — CVV
  - `customer` CustomerReqDTO — Customer information
    - `merchantCustomerId` string — Customer ID
    - `firstName` string — First name
    - `lastName` string — Last name
    - `dateOfBirth` string — Date of birth
    - `phoneNumber` string — Phone number
    - `idCard` string — ID card
    - `idType` string — ID type
    - `email` string — Email
  - `goods` GoodsReqDTO[] — Product list
    - `name` string — Product name
    - `sku` string — Product SKU
    - `url` string — Product URL
    - `quantity` integer — Product quantity
    - `price` string — Unit price
    - `totalAmount` string — Total amount
    - `totalDiscountAmount` string — Total discount amount
    - `productType` string — Product type
  - `shippingInfo` ShippingInfoReqDTO — Shipping information
    - `firstName` string — Shopper's first name
    - `lastName` string — Shopper's last name
    - `shippingAddress` BaseAddressReqDTO — Billing address
      - `addressLine1` string — Address line 1
      - `addressLine2` string — Address line 2
      - `city` string — City
      - `state` string — State/Province
      - `country` string — Country code
      - `postalCode` string — Postal code
  - `billInfo` BillInfoReqDTO — Billing information
    - `firstName` string — Billing person's first name
    - `lastName` string — Billing person's last name
    - `billAddress` BaseAddressReqDTO — Billing address
      - `addressLine1` string — Address line 1
      - `addressLine2` string — Address line 2
      - `city` string — City
      - `state` string — State/Province
      - `country` string — Country code
      - `postalCode` string — Postal code
  - `merchant` MerchantReqDTO — Merchant information
    - `subMerchantId` string — Sub-merchant ID (acquiring system sub-merchant ID, long type)
  - `additionalInfo` AdditionalInfoReqDTO — Additional acquiring parameters
    - `transferReference` string — Merchant transaction ID for AFT and FT transactions
  - `description` string — Merchant-provided information, will be returned as-is

## Response `200`

OK

- AcquiringPaymentCreateResultVO
  - `code` integer — Return code
  - `message` string — Error message
  - `data` AcquiringPaymentCreateVO, required — Payment order object
    - `tradeNo` string — Order number
    - `merchantTradeNo` string — Merchant order number
    - `amount` number — Order amount
    - `currency` string — Order currency
    - `orderStatus` 'PENDING' | 'READY' | 'PAID' | 'FAILED' | 'CANCELED' | 'REFUNDED' | 'CANCELING' | 'AUTHORIZED' | 'REFUNDING' | 'CAPTURED' | 'CLOSED' — Order status PENDING: Order Creation in Progress READY: Waiting for Customer Payment PAID: Order Paid FAILED: Order Failed CANCELED: Order Canceled by Customer REFUNDED: Order Refunded CANCELING: Order Canceling AUTHORIZED: Order Authorized REFUNDING: Order Refunding CAPTURED: Payment Captured CLOSED: Order Closed (Typically due to Expiration)
    - `orderType` 'UNDEFINED' | 'PAYMENT' | 'REFUND' — Order type
    - `createTime` string — Order creation time
    - `completeTime` string — Order completion time
    - `chargeToken` string — Payment token
    - `action` PaymentActionVO — Next action
      - `redirectToPay` string — URL to redirect to payment page
      - `redirectTo3DS` string — URL to redirect to 3DS page
    - `merchant` ApiMerchantVO — Merchant information
      - `subMerchantId` string — Sub-merchant ID (acquiring system sub-merchant ID)
    - `ticket` PaymentTicketVO — Ticket information
      - `number` string — Ticket number
      - `expirationDate` string, date-time — Ticket expiration date
      - `barcode` string — Ticket barcode information
      - `format` string — Ticket format
      - `currency` string — Currency
      - `amount` number — Amount
    - `orderChain` AcquiringChainVO — Order chain info
      - `chainType` string — Cryptocurrency chain type
      - `chainAddress` string — Payment chain address
    - `description` string — Merchant-provided information, will be returned as-is

## Other responses

- `400` — Bad Request
- `500` — Internal Server Error

---

[API](https://skmtc.net/interlace/apis/core-resource.md) · [All operations](https://skmtc.net/interlace/apis/core-resource/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/interlace/core-resource/revisions/29c08a4da357/schema)