Payment

ATM/Visa/Mastercard payments support token-saving payments (save card information for future payments)

(only supports some providers)

EndPoint

POST /api/v2/orders/payment

Header Params

Params	Requirement	Data type	Description	Note
X-APPOTAPAY-AUTH	required	String	To create a JWT_TOKEN
Content-Type	required	String	Value: application/json
X-Request-ID	optional	String	Format is UUIDv4. Request ID for troubleshooting purposes	max:42
X-Language	optional	String	Value vi or en,The value corresponding to the payment link can be in Vietnamese or English (default: vi)	in:vi,en
X-Account-Ref-ID	optional	String	Iidentifier of the sub account provided by AppotaPay. Mandatory be passed over when processing payment for transactions of owner-type sub account

{
    "X-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "X-Language": "vi",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Request Params

Params	Requirement	Data type	Description	Note
transaction	required	Object	Transaction information
transaction.amount	required	Integer	The payment amount
transaction.currency	required	String	Currency unit(VND)	Accepted: VND
transaction.bankCode	optional	String	Refer to Bank code table
transaction.paymentMethod	required	String	Refer to Payment method code table
transaction.action	required	String	Action payment
transaction.token	optional	String	Token used for payment (in case of using token)
partnerReference	required	Object	Partner information
partnerReference.order.id	required	String	Partner's order code	50
partnerReference.order.info	required	String	Order information (maximum 150 characters)	150
partnerReference.order.extraData	optional	String	Optional additional information	200
partnerReference.notificationConfig.notifyUrl	required	String	URL to receive transaction results	100
partnerReference.notificationConfig.redirectUrl	required	String	Redirect URL in the browser	100
partnerReference.notificationConfig.deeplinkUrl	optional	String	Redirect result to app mobile	100
partnerReference.notificationConfig.installmentNotifyUrl	optional	String	IPN for installment conversion transaction notification	100

Example Request

{
  "transaction": {
    "amount": 10000,
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY"
  },
  "partnerReference": {
    "order": {
      "id": "5f61cf4f41e2b",
      "info": "test thanh toan",
      "extraData": ""
    },
    "notificationConfig": {
      "notifyUrl": "https://devtool.vn/ipn",
      "redirectUrl": "https://devtool.vn/redirect",
      "installmentNotifyUrl": "https://devtool.vn/redirect"
    }
  }
}

Response Params

Params	Requirement	Data type	Description
transaction	required	Object	Transaction information
transaction.transactionId	required	String	The transaction code on AppotaPay's side
transaction.status	required	String	Transaction status
transaction.errorCode	required	Integer	[Error code](./payment.mdx#error code table)
transaction.errorMessage	required	String	Error description
transaction.partnerCode	required	String	partner code
transaction.orderAmount	required	Integer	Payment amount (Min: 1000, Max: 500000000)
transaction.currency	required	String	Currency unit
transaction.bankCode	required	String	bankcodeThe customer has selected
transaction.paymentMethod	required	String	Payment Method
transaction.action	required	String	Type of payment
transaction.createdAt	required	String	Transaction creation time. (in RFC-3339 standard format)
transaction.updatedAt	required	String	Transaction update time. (in RFC-3339 standard format)
payment	required	Object
payment.url	required	String	Payment URL, the 'lang' parameter in the payment link can be changed to 'vi' or 'en' corresponding to the customer's desired language
payment.qrCode	optional	Object	Returned in case of payment with QR code
payment.qrCode.url	optional	String	QR payment URL
payment.qrCode.content	optional	String	QR content to generate the payment QR code
payment.qrCode.expiry	optional	String	QR payment expiration time. (in RFC-3339 standard format)
payment.deepLinkUrl	optional	String	Link to open payment app if available

Success

Http Status Code 200 - OK

{
  "transaction": {
    "transactionId": "AP123",
    "status": "pending",
    "errorCode": 35,
    "errorMessage": "The transaction is pending, please check it later",
    "partnerCode": "TEST",
    "orderAmount": 10000,
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY",
    "createdAt": "2024-04-01T14:46:20.000",
    "updatedAt": "2023-04-01T14:46:20.000"
  },
  "payment": {
    "url": "https://payment.dev.appotapay.com/v2/bank/payment/process?tran=dGlkPUFQMjMxNDQwNDkwODI0Jm9yZGVySWQ9YVY2a01uakR2JnRzPTE2OTkyMzYwNTQ&sign=bfff37df0d919ac1ea9d7163934bbc8ce785c6bbf7a210fb12696c8e531532ed&lang=vi",
    "qrCode": null,
    "deepLinkUrl": ""
  }
}

Error

HTTP Status Code != 200 With the returned errorCode, please refer to the error code table here

Error response params

Params	Requirement	Data type	** Description**
errorCode	required	Integer	Error code
message	required	String	Error description
errors	optional	Array of Object	Detailed error description of each field if available
errors.field	required	Object	Field with error
errors.reason	required	Object	Description of the field with error

{
  "errorCode": 1,
  "message": "Invalid Params",
  "errors": [
    {
      "field": "transaction.amount",
      "reason": "Field amount is required"
    },
    {
      "field": "transaction.currency",
      "reason": "Field currency is required"
    }
  ]
}

Error code table

Error code	Description
1	Missing or invalid request information
30	The order code is duplicated, please redo the transaction.
32	The amount is invalid.
140	The partner does not have permission to use the paymentMethod
141	The partner does not have permission to use the bankCode
500	The system encountered an error, please try again later