API Create payment method

Endpoint: /api/v1/subs/payment-methods

Method: POST

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-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "Language": "vi"
}

Request params

Param	Required	Type	Description	Note
partnerRefId	Required	String	Unique reference code of partner	min:1, max: 50, format: alphanumeric
customerId	Conditional, if customer object doesn't have information	String	Customer ID is created when calling ‘Create customer’ API
customer	Conditional, if customer ID doesn't have information	Object	Customer information
customer.firstName	Conditional	String	First name	min:1, max: 50
customer.lastName	Optional	String	Last name	min:1, max: 50
customer.mobileNumber	Optional	String	Phone number Format: +[Country code][Phone number] Example: +84919333777	min:1, max: 16, format: E.164
customer.email	Optional	String	Email	min:1, max: 50
customer.gender	Optional	String	Gender - MALE: male - FEMALE: female - OTHER: other	in: MALE, FEMALE, OTHER
customer.dateOfBirth	Optional	String	Date of birth	format YYYY-MM-DD string
customer.placeOfBirth	Optional	String	Place of birth	max: 50
customer.nationality	Optional	String	Nationality code	format ISO 3166-2 Country Code
country	Required	String	Country code of transaction Accepted value - ID: Indonesia - PH: Philippines - VN: Vietnam - TH: Thailand - MY: Malaysia	Format ISO 3166-2 Country Code
currency	Required	String	Currency unit	in: VND
paymentMethod	Required	String	Payment method - CC_SUBS: payment with credit card - EWALLET_SUBS: payment with ewallet	in: CC_SUBS, EWALLET_SUBS
reusability	Required	String	Describes whether or not the payment method can be reused for subsequent payments. - MULTIPLE_USE: may be reused for subsequent payments	in: MULTIPLE_USE
card	Conditional, required if paymentMethod = 'CC_SUBS'	Object	Card information
card.properties	Conditional, required if paymentMethod = 'CC_SUBS'	Object	Properties
card.properties.skipThreeDSecure	Conditional, required if paymentMethod = 'CC_SUBS'	String	This field value is only configurable for reusability = MULTIPLE_USE to indicate whether to perform 3DS during the linking phase. - YES: skip to perform 3DS - NO: perform 3DS	in: YES, NO
card.properties.successReturnUrl	Conditional, required if skipThreeDSecure = NO	String	URL where the end-customer is redirected if the linking is successful.	max:100
card.properties.failureReturnUrl	Conditional, required if skipThreeDSecure = NO	String	URL where the end-customer is redirected if the linking is failed.	max:100
card.cardInfo	Conditional, required if paymentMethod = 'CC_SUBS	Object	Card information
card.cardInfo.cardNumber	Conditional, required if paymentMethod = 'CC_SUBS'	String	Card number	max: 20
card.cardInfo.cardMonth	Conditional, required if paymentMethod = 'CC_SUBS'	String	Card expiry month, contain the leading zero (E.g. 03)	format: MM
card.cardInfo.cardYear	Conditional, required if paymentMethod = 'CC_SUBS'	String	Card expiry year (E.g. 2024))	format: YYYY
card.cardInfo.cardHolderName	Optional	String	Card holder name	max: 50
ewallet	Conditional, required if paymentMethod = 'EWALLET_SUBS'	Object	Ewallet information
ewallet.serviceCode	Conditional, required if paymentMethod = 'EWALLET_SUBS'	String	Ewallet code
ewallet.properties	Conditional, required if paymentMethod = 'EWALLET_SUBS'	Object	Properties
ewallet.properties.successReturnUrl	Conditional, required if paymentMethod = 'EWALLET_SUBS'	String	URL where the end-customer is redirected if the linking is successful.
ewallet.properties.pendingReturnUrl	Conditional, required if paymentMethod = 'EWALLET_SUBS'	String	URL where the end-customer is redirected if the linking is pending.
ewallet.properties.failureReturnUrl	Conditional, required if paymentMethod = 'EWALLET_SUBS'	String	URL where the end-customer is redirected if the linking is failed.
billing	Optional	Object	Billing information
billing.country	Required if any field in object has data	String	Country code	Format ISO 3166-2 Country Code
billing.city	Required if any field in object has data	String	City	min:1, max: 50
billing.provinceState	Required if any field in object has data	String	Province/ state	min:1, max: 50
billing.address	Required if any field in object has data	String	Address	min:1, max: 100
billing.zipcode	Required if any field in object has data	String	Zip code	min:1, max: 10, format: numeric

Example Request

{
    "partnerRefId": "ASKJLKALK16640",
    "customer": {
        "firstName": "Ha",
        "lastName": "Phan",
        "mobileNumber": "+84123456789",
        "email": "ha@gmail.com",
        "gender": "MALE",
        "dateOfBirth": "1996-04-23",
        "placeOfBirth": "HN",
        "nationality": "EC"
    },
    "country": "VN",
    "currency": "VND",
    "paymentMethod": "CC_SUBS",
    "reusability": "MULTIPLE_USE",
    "card": {
        "properties" : {
           "skipThreeDSecure": "NO",
           "successReturnUrl": "https://devtool.vn/success",
           "failureReturnUrl": "https://devtool.vn/failure"
        },
        "cardInfo" : {
           "cardNumber": "5200000000001096",
           "cardMonth": "07",
           "cardYear": "2034",
           "cardHolderName": "Mai Minh"
        }
    },
    "billing": {
        "country": "EC",
        "city": "HN",
        "provinceState": "CG",
        "address": "CG",
        "zipcode": "530000"
    }
}

Response data

Success

Http Status Code 200 - OK

Success responses will contain a single Payment method object

Failure

HTTP Status Code != 200

Error response params

Param	Required	Type	Description
errorCode	required	Integer	Error code
message	required	String	Error message
errors	optional	Array	Detailed error description
errors.*.field	optional	String	Field data is corrupted
errors.*.reason	optional	String	Description of the data field in error

{
    "errorCode": 1,
    "message": "Missing or Invalid Params",
    "errors": [
        {
            "field": "partnerRefId",
            "reason": "The partner ref id field is required."
        }
    ]
}

Common error code table

Full error code, please check this error code list

Error code	Description
0	Success
1	Missing or Invalid Params
11	Partner is not found
13	Partner has been blocked
14	API Key is invalid
15	API Key is not activated or blocked
92	IP is not allowed to access
99	Undefined error, please contact AppotaPay for more detailed information
401	Unauthorized
500	Server error
3002	Duplicate partnerRefId, please try again
3003	Customer not exist
3013	3D Secure is required
3027	Customer's information is invalid