Charge Create

You can request charge by token or card information. A charge consists of two sub-processes:

• Authorization: Confirming with the issuing bank that the card is eligible for transaction and is able to pay. At this point, the money is put on hold and settlement has not started yet.

• Capture: The transaction is locked to be completed and the settlement process will be started.

EndPoint

POST /credit-card/charge

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
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",
    "Language": "vi",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Request Params

Parameters	Requirement	Data type	Description	Note
card	required	Object	Card information
card.number	required	String	Card number	16 numbers
card.holderName	required	String	Card holder	Min: 1 Max: 50 Including: 0- 9, a-z, A-Z, Space
card.expirationMonth	required	String	Card expiration month, including leading 0 (E.g.: 03 for March)	Format: MM
card.expirationYear	required	String	Card expiration year (E.g.: 25)	Format: YY
card.cvv	required	String	Card verification number, also known as CVV The card's secret code includes 3 or 4 numbers
tokenId	required_if	String	Required if card isn't provided Token ID for payment instead of card information
amount	required	Float	Amount of the payment processed on the card, being submitted for authentication (E.g.: 1000)	Support VND
capture	optional	Boolean	Default: false Whether or not to capture immediately Set to true to perform Authorization and Capture immediately. Set to false to issue an Authorization (hold funds) only, to be captured later with the Capture Charge Note: Authorizations expire in 7 days.
merchantRefId	required	String	Reference ID you can use to identify the transaction	Min: 1 Max: 40
authenticationId	required_if	String	Unique authentication ID returned by AppotaPay during in the 3DS Authentication response (or callback) to identify the 3DS transaction. For transactions where you do not want to initiate 3DS Authentication and proceed straight to an Authorization / Charge, do not include this parameter in the Charge request. Note: Required when config 3ds is required	Min: 1 Max: 40
currency	required	String	Payment currency. Should be a 3-letter code following the ISO-4217 standard	Support: VND
billing	optional	Object	Billing details of the cardholder. If entered, should correspond with billing details registered by the cardholder with their issuer. If entered billing information, you need to enter all information and correspond as registered to your issuing bank.
billing.firstName	optional	String	First name of cardholder Useful with frictionless 3DS 2.0	Min: 1 Max: 50
billing.lastName	optional	String	Last name of cardholder Useful with frictionless 3DS 2.0	Min: 1 Max: 50
billing.email	optional	String	Cardholder’s email address on record with issuer Useful with frictionless 3DS 2.0	Min: 1 Max: 255
billing.phoneNumber	optional	String	Cardholder’s mobile phone number on record with issuer Useful with frictionless 3DS 2.0	Min: 8 Max: 20
billing.province	optional	String	Use this to enter province, state or region of residence. If the user is USA citizen, make sure to use state code (e.g put CA instead of California) Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.city	optional	String	City, village or town as appropriate Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.country	optional	String	2-letter ISO 3166-2 country code for the customer's country of residence Useful with frictionless 3DS 2.0	Min: 2 Max: 2
billing.addressLine1	optional	String	Building name and apartment unit number Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.addressLine2	optional	String	Building name and apartment unit number Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.postalCode	optional	String	Postal, zip or rural delivery code, if applicable Useful with frictionless 3DS 2.0	Min: 1 Max: 10

Example Request

{
    "merchantRefId": "hi8xGfznb",
    "authenticationId": "01HQHRPNYW78CQJK7CAW1SJP9F", 
    "tokenId": "01hqhrp3yhff7z7bvtq6whwz8t", 
    "amount": 1000000,
    "currency": "VND",
    "capture": false,
    "billing" : {
        "firstName": "NHUNG",
        "lastName": "HOANG",
        "email": "nhunghoang@email.com",
        "phoneNumber": "02345686432",
        "province": "VP",
        "country": "MM",
        "city": "VT",
        "addressLine1": "81 Lang Ha",
        "addressLine2": "17 Mai Anh Tuan",
        "postalCode": "10000"
    }
}

Response Params

{
    "id": "01HQHRS9P9J5YPCJ09D94VW84F",
    "authenticationId": "01HQHRPNYW78CQJK7CAW1SJP9F",
    "merchantRefId": "hi8xGfznb",
    "status": "AUTHORIZED",
    "authorizedAmount": 1000000,
    "currency": "VND",
    "approvalCode": "831000",
    "eci": "02",
    "bankReconciliationId": "7089196646896845103954",
    "tokenId": "01hqhrp3yhff7z7bvtq6whwz8t",
    "card": {
        "number": "520000XXXXXX2151",
        "expirationMonth": "12",
        "expirationYear": "29",
        "cardBrand": "MASTERCARD",
        "cardType": "CREDIT",
        "countryCode": "VI"
    },
    "chargeType": "BY_MULTIPLE_TOKEN",
    "createdAt": "2024-02-26T10:54:22+07:00",
    "updatedAt": "2024-02-26T10:54:25+07:00"
}

Success

Http Status Code 200 - OK

Parameters	Data type	Description
merchantRefId	String	A unique identifier of merchant is sent in the request
card	String	Card information is stored in the token
card.number	String	1st 6 and last 4 digits of the tokenized card. (E.g. 123456xxxxx1234)
card.expirationMonth	String	Card expiration month, including leading 0 (E.g.: 03 for March)
card.expirationYear	String	Card expiration year (E.g.: 27)
card.brand	String	Card brand: VISA / MASTERCARD / JCB / AMEX
card.country	String	Country of the card issuing bank in ISO 3166-1 alpha-2 format (E.g.: VN, US)
reconciliationId	String	ID of the transaction that can be reconciled with AppotaPay
bankReconciliationId	String	ID of the transaction that can be reconciled with bank
authorizedAmount	Number	The amount that've been authorized for this charge
capturedAmount	Number	The amount that've been captured for this charge. Can be up to authorizedAmount
currency	String	Payment currency
status	String	Status of the charge PENDING: Payment is processing. CAPTURED: Charge is successfully captured and the funds will be settled according to the settlement schedule. AUTHORIZED: Charge is successfully authorized. PARTIAL_AUTHORIZED: Charge is successfully partial authorized. DECLINED: Charge failed
eci	String	3DS authentication status. See ECI code
id	String	ID of the transaction Id can be used in many APIs such as: Capture API, Reversal API, Refund API or Get Charge API (if meeting conditions)
approvalCode	String	Code from issuer bank returned
errorInformation	Object	Failure reason
errorInformation.errorCode	Integer	Error code. See error code
errorInformation.message	String	Error message
errorInformation.details	Array or Object	Error details
errorInformation.details.field	String	Failure field
errorInformation.details.reason	String	Reason why the field failed
chargeType	String	Charge type - BY_SINGLE_TOKEN - BY_MULTIPLE_TOKEN - BY_CARD_INFO
createdAt	String	Transaction creation time according to RFC-3339 standard, time zone UTC+7
updatedAt	String	Last updated time according to RFC-3339 standard, time zone UTC+7

Error

HTTP Status Code != 200