Payment integration

Payment integration

Chat with AI▼

EndPoint

POST /api/v2/orders/create-payment

Header Params

Param	Required	Type	Description	Note
X-APPOTAPAY-AUTH	required	String	How to generate JWT_TOKEN
Content-Type	required	String	Value: application/json
X-Request-ID	optional	String	UUIDv4 format. Request ID to check when a problem occurs	max:42
X-Language	optional	String	The value vi or en corresponding to the payment link will be 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

Param	Required	Type	Description	Note
transaction	required	Object	Transaction information
transaction.amount	required	Integer	Payment amount
transaction.currency	required	String	Payment currency(VND)	Support VND
transaction.bankCode	required	String	Check Bank code list
transaction.paymentMethod	required	String	Check Payment method list
transaction.action	required	String	Payment action which partner can request (PAY), default: PAY	Support PAY
sourceOfFunds	required	Object	Payment card/account information
sourceOfFunds.type	required	Object	Payment type (Card / Account)	Support Card / Account
sourceOfFunds.card	required_if	Object	Card object	Required if type is card
sourceOfFunds.card.cardNumber	required	String	Card number
sourceOfFunds.card.cardHolderName	required	String	Card holder
sourceOfFunds.card.cardMonth	required	String	Issue/ Expiry month on card Following the docs: LINK
sourceOfFunds.card.cardYear	required	String	Issue/ Expiry year on card Following the docs: LINK
sourceOfFunds.account	required_if	Object	Account object	Required if type is account
sourceOfFunds.account.accountNumber	required	String	Account number
sourceOfFunds.account.accountHolderName	required	String	Account holder
sourceOfFunds.account.identificationNumber	required	String	Identification number
partnerReference	required	Object	Partner information
partnerReference.order.id	required	String	Order id of partner	Max: 50
partnerReference.order.info	required	String	Order information (max: 150 characters)	Max: 150
partnerReference.order.extraData	optional	String	Additional information	Max: 200
partnerReference.notificationConfig.notifyUrl	required	String	IPN URL to receive the transaction result	Max: 100
partnerReference.notificationConfig.redirectUrl	required	String	URL to redirect on browser	Max: 100

Example Request

{
  "transaction": {
    "amount": 10000,
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY"
  },
  "sourceOfFunds": {
    "type": "card",
    "card": {
      "cardNumber": "9704000000000018",
      "cardHolderName": "NGUYEN VAN A",
      "cardMonth": "03",
      "cardYear": "07"
    }
  },
  "partnerReference": {
    "order": {
      "id": "5f61cf4f41e2b",
      "info": "test thanh toan",
      "extraData": ""
    },
    "notificationConfig": {
      "notifyUrl": "https://devtool.vn/ipn",
      "redirectUrl": "https://devtool.vn/redirect",
    }
  }
}

Response Params

Param	Required	Type	Description
transaction	required	Object	Transaction information
transaction.transactionId	required	String	Transaction id of AppotaPay
transaction.status	required	String	Transaction status
transaction.errorCode	required	Integer	Error code list
transaction.errorMessage	required	String	Error detail
transaction.partnerCode	required	String	Partner code
transaction.amount	required	Integer	Payment amount
transaction.orderAmount	required	Integer	Order amount
transaction.fee	required	Object	Payment fee
transaction.fee.customer_fee	required	String	Payment fee for customer
transaction.currency	required	String	Payment currency
transaction.bankCode	required	String	Check Bank code list
transaction.paymentMethod	required	String	Check Payment method list
transaction.action	required	String	Payment action which partner can request (PAY), default: PAY
transaction.createdAt	required	String	Transaction creation time (standard format: RFC-3339)
transaction.updatedAt	required	String	Last updated time (standard format: RFC-3339)
authentication	required	Object
authentication.verificationUrl	required	String	URL to verify payment
authentication.verificationMethod	required	String	Verification method is used in the transaction (support: OTP)
authentication.verificationStatus	required	String	Verification status for the transaction

Success

Http Status Code 200 - OK

{
  "transaction": {
    "transactionId": "AP123",
    "status": "pending",
    "errorCode": 35,
    "errorMessage": "Giao dịch đang chờ xử lý",
    "partnerCode": "TEST",
    "amount": 11327,
    "orderAmount": 10000,
    "fee": {
      "customer_fee": 1327
    },
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY",
    "createdAt": "2023-11-13 15:23:40.000",
    "updatedAt": "2023-11-13 15:23:40.000"
  },
  "authentication": {
    "verificationUrl": "https://ibanking.dev.appotapay.com/domestic-card/napas/confirm-otp?tran=eyJ0cmFuc0lkIjoiMDFIUjY4UFA3NEgxS1RINjNTV0ZKVllDNE4iLCJkYXRhS2V5IjoiNjdydzl4VFpLdEt0TTh4ZGtiRDlKYVhZbVROM1BCdlVHWDZIcnJpeTFuRGIwUksvRkp5Z2ZiWEo2SUt6U2ZWZGtwTmhEYmp1MTcxNXFqbWpndUlyL20xWTVtT0VKS0NlcEIwOCtQamlSZit2R2xEcTlFeU9FV3FjVnBEVjI4UWswbzQ5eEtTRXNFanBBZWJoRVNZMUNRRnlmWVMwU2NiQnJha0xWZ1FOMng3WTBUeGc4Uk9ESFhLK1N4SG80NFRNWUxtRkdSWk0xNExpOHBONHhrNWlyN1EvRkVoVVBqSDQ2aE50aCtQSFRkeW5MNlVKcnlOOEphcVdXaUNJOU1uVFJhcklraFU3MUlkU3REWFdwMlNQcEVhSTRZUGZuRElhZGhnRWF6Zk9WWm0zUjJibUxIMHllTEEwZndXTDY3VHk1ZFZpOUZwVWp4R01iZDZnMHB3eDNnZG1TcUkreHJLbTRJTUo4TEErN0JNU3JJTW9rUHVqZkY0UGd4Vk9vd3QrNUl4c0kvek40eGlPa1VjUWFwdWhoOTlpa1l0YTViNEpYTks3THZ3VVltYz0iLCJuYXBhc0tleSI6Ik1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBcmJQNmlGbDBaOXBESHY1bmkvZmhsNE1FNkFmUDE2RTV6bXJIWWZ0YUJsY3ZxMWJXUndrMVRIMjNPcllRNm42akVHSWJtclZYeklNMDBsazcyMy9aSHR2YnlabGQ4cjVUY0VoNU0raC9qSXUzL0o5Z3FOWUdUbzlqTEowRHZSZFNmemJEV0pxUEltUGZjR0pEUlBUckV0Y2txbWQ4SHZrVTZKM01DUHJnMElPR1RZcGxVbXc2RFoyNWcxU3BCU2IxQ0FXR3FQMzZucXl4Tlo0aE5KMDhhZ0hRYlJjL0lDSFViLzgrL1VqREVUWDk2U1lWbitHQktick1NL05jZ2lKVjdVWGJFbVE5T0VpTTNCYkk1c3JoQ090MG9Zb0NwMHNKY3BMY0xiUmxwZEM3L25WNDRLUHR5MXJrWjMyS2xCdWZ6M1VWZ2dYcEhQejBrMHl4WVR2bC93SURBUUFCOk1JSUN0VENDQVowQ0JnRm9rbzg5K0RBTkJna3Foa2lHOXcwQkFRVUZBREFlTVJ3d0dnWURWUVFERXhOVVpYTjBJRU5CSUVObGNuUnBabWxqWVhSbE1CNFhEVEU1TURFeU9EQXpORFEwTjFvWERURTVNREV5T1RBek5EUTBOMW93SGpFY01Cb0dBMVVFQXhNVFZHVnpkQ0JEUVNCRFpYSjBhV1pwWTJGMFpUQ0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQ0FRb0NnZ0VCQUsyeitvaFpkR2ZhUXg3K1o0djM0WmVEQk9nSHo5ZWhPYzVxeDJIN1dnWlhMNnRXMWtjSk5VeDl0enEyRU9wK294QmlHNXExVjh5RE5OSlpPOXQvMlI3YjI4bVpYZksrVTNCSWVUUG9mNHlMdC95ZllLaldCazZQWXl5ZEE3MFhVbjgydzFpYWp5SmozM0JpUTBUMDZ4TFhKS3BuZkI3NUZPaWR6QWo2NE5DRGhrMktaVkpzT2cyZHVZTlVxUVVtOVFnRmhxajkrcDZzc1RXZUlUU2RQR29CMEcwWFB5QWgxRy8vUHYxSXd4RTEvZWttRlovaGdTbTZ6RFB6WElJaVZlMUYyeEprUFRoSWpOd1d5T2JLNFFqcmRLR0tBcWRMQ1hLUzNDMjBaYVhRdS81MWVPQ2o3Y3RhNUdkOWlwUWJuODkxRllJRjZSejg5Sk5Nc1dFNzVmOENBd0VBQVRBTkJna3Foa2lHOXcwQkFRVUZBQU9DQVFFQUZYSzQ4cDcxUzg3RW1ybkNtNVl2djQyT3h6aDBCMTgvcTRqbjg5MXhTMWFiRlJrVzJqZEN2cGMzSVVRTDZneStKRlFjWTJOU2FMaElZZ0JhZm1jbmdpQkZ0NGtrVHFVdXdTZElXdWRsM2pZa081OFNPWUtkeFc4amJYTTVLd1R1anBiMGdZQnBmMXU1ODI4Um1FcTZZRW9nL3l4L2hZUU9GUWxmSUJCWkZObVVKN1U1VERDRkwyd1Q1TXFQZzJjZmIxRGlydmVEM3NMU0lVYzkwSUpNM2VVWGZ6WHFrd2RyQ0tEWlJTdVYzVE1IQ2hpMUlSaW8yZmc3emVzaTlIbGlGdWVhZWtrdnlubndYb0c0MUxLYU1TQk1NL01kcmIydG0yOWpWWW5sWUo4Q29qK2RPaldoVTJ5ODNkRmk1REdyOGEzZnRXT2MrckV6MnpsT1VLUkY3UT09IiwiZXhwaXJ5RGF0ZSI6MTcwOTYwOTI0NSwiY2xpZW50SXAiOiIxMjcuMC4wLjEiLCJkZXZpY2VJZCI6IkRJMTc4MzQ2MzUyNSIsInBhbmVyQ29kZSI6Ilh1QXBwb3RhUGF5IiwiUGFydG5lck5hbWUiOiJYdUFwcG90YVBheSIsImFwaU9wZXJhdGlvbiI6IlBVUkNIQVNFX0FDQ09VTlQiLCJsYW5ndWFnZSI6InZpIiwidmVyc2lvbiI6InYxIn0=&sign=97b25a7e38d6501bbaeb4fa0793670209e3f6987e9c48f6b1fc58f0d828f79fa",
    "verificationMethod": "OTP",
    "verificationStatus": "AUTHENTICATE_REQUIRED"
  }
}

Failure

HTTP Status Code != 200 HTTP Status Code != 200 with errorCode, please check this Error code list

Error response params

Param	Required	Type	Description
errorCode	required	Integer	Error code
message	required	String	Error detail
errors	optional	Array of Object	Describe error detail for fields (if any)
errors.field	required	Object	The fields occur error
errors.reason	required	Object	Error reason

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

Error code list

Error code	Description
1	Missing or Invalid params
30	Duplicate orderId, please try again
32	Invalid amount
90	X-Account-Ref-ID is invalid
140	Partner does not have permission to use the paymentMethod
141	Partner does not have permission to use the bankCode
500	Server error

Code Examples

curl --location 'https://gateway.dev.appotapay.com/api/v2/orders/create-payment' \
  --header 'X-APPOTAPAY-AUTH: JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Request-ID: Your_Unique_id' \
  --header 'X-Language: vi' \
  --header 'X-Account-Ref-ID: 9723f73b-9295-4acb-884b-ab6310c2e653' \
  -d '{
  "transaction": {
    "amount": 10000,
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY"
  },
  "sourceOfFunds": {
    "type": "card",
    "card": {
      "cardNumber": "9704000000000018",
      "cardHolderName": "NGUYEN VAN A",
      "cardMonth": "03",
      "cardYear": "07"
    }
  },
  "partnerReference": {
    "order": {
      "id": "5f61cf4f41e2b",
      "info": "test thanh toan",
      "extraData": ""
    },
    "notificationConfig": {
      "notifyUrl": "https://devtool.vn/ipn",
      "redirectUrl": "https://devtool.vn/redirect"
    }
  }
}'

Request

REQUEST

Base URL

https://gateway.dev.appotapay.com

Development server

Path

Auth REQUIRED

Bearer Token

X-Language — header

vien

The value corresponding to the payment link can be in Vietnamese or English (default: vi)

Parameters

Body REQUIRED

Example (from schema)

{ "transaction": { "amount": 10000, "currency": "VND", "bankCode": "VCB", "paymentMethod": "ATM", "action": "PAY" }, "sourceOfFunds": { "type": "card", "card": { "cardNumber": "9704000000000018", "cardHolderName": "NGUYEN VAN A", "cardMonth": "03", "cardYear": "07" } }, "partnerReference": { "order": { "id": "5f61cf4f41e2b", "info": "test thanh toan", "extraData": "" }, "notificationConfig": { "notifyUrl": "https://devtool.vn/ipn", "redirectUrl": "https://devtool.vn/redirect" } } }