Payment Methods Payload
This section is to guide integrators in understanding different payment methods payload for each types of payment method. Ezypay's payment method payload is made up of 2 different parts:
- Generic Payment Methods Information
- Specific Payment Method Data
Generic Payment Methods Information
This contains general information of the payment method. These fields are same among all payment methods.
{
"paymentMethodToken": "a0103b2d-a5c3-40f1-9f8b-3856033ac069",
"customerId": "c623b717-234a-442c-961c-12e2d80e02ff",
"type": "PAYTO",
"bank": null,
"payTo": {"some data"
},
"card": null,
"invalidReason": {
"code": "mandate_created",
"description": "Mandate is created but not activated yet."
},
"lastUsedOn": null,
"replacedPaymentMethodData": null,
"wallet": null,
"valid": false,
"primary": true
}
Payload Field | Description | Details |
---|---|---|
paymentMethodToken | Payment Method Token | This is the unique token linked to a specific payment method data stored in Ezypay vault. |
customerId | Ezypay's Customer UUID | Unique ID of the customer registered in Ezypay that linked to the payment method. |
type | Payment Method Type | Indicating which type this payment method token belongs to. 4 possible value. 1. PAYTO 2. WALLET 3. BANK 4. CARD |
bank , payTo , card , wallet | Information about the underlying payment methods | These fields shows the truncated data of the underlying payment method of the token. Only the field corresponding to the type field will contains data. Others will return as null . |
invalidReason | Reason on why the payment method is invalidated | Return null if the payment method is still valid, else return an object specifying the invalid reasons. The object contain 2 fields:a) code - the failure codeb) description - Description for the failure code. |
lastUsedOn | Payment Method Last used date | Shows the date and time the payment method was last used on in ISO 8601 format. If it is not used before, will show null . |
replacedPaymentMethodData | Payment Method Data that is being replaced | Only applicable when replacing a payment method, otherwise it will be null . It contains a payment method object with all the same fields as the payment method payload. |
valid | Valid flag of the payment method | Indicates whether the payment method is valid or not. True - This payment method is valid False - This payment method is invalid |
primary | Primary flag of the payment method | Indicates whether the payment method is primary or not. True - This payment method is primary False - This payment method is not primary. |
Specific Payment Method Data
Table below shows the difference on the data for different payment method type. Please take note only truncated data is returned for sensitive data.
{
"type": "CARD",
"card": {
"accountHolderName": "John Smith",
"expiryYear": "25",
"expiryMonth": "01",
"type": "VISA",
"last4": "1111",
"first6": "411111",
"origin": null,
"countryCode": "AU",
"tokenDetails": {
"tokenType": "visa",
"friendlyDisplay": null,
"originalLast4": "1111",
"tokenFirst6": "481852",
"tokenLast4": "3021",
"tokenExpiry": "01-30"
},
"tokenized": true
}
}
{
"type": "BANK",
"bank": {
"accountHolderName": "John Smith",
"last4": "1534",
"bankNumber": "062140",
"branchNumber": "2140",
"suffixNumber": "06",
"countryCode": "AU",
"bankTransferType": "LOCAL"
}
}
{
"type": "wallet",
"wallet": {
"accountHolderName": "John Smith",
"accountMobileNumber": "+63966164540",
"type": "gcash",
"merchantId": "bfdaa558-0779-4df0-98a0-41280e9dd805",
"walletPaymentProviderId": "5cafeb170a2b18519b1b8761",
"countryCode": "PH"
}
}
{
"type": "PAYTO",
"payTo": {
"accountHolderName": "John Smith",
"accountType": "ALIA",
"aliasType": "TELI",
"aliasId": "+61-412345678",
"merchantId": "1aefbba9-263a-484f-8ba1-1b074b8c1493",
"mandateTypeId": "bd0d2201-92ac-432a-80d1-fc884be19dba",
"mandateStatus": "CRTD",
"mandateReason": "Created.",
"mandateId": "504544b4c810457f9c94793455ed50b9",
"description": "Payment for JGym Membership",
"frequency": "ADHO",
"validityStartDate": "2024-07-30T07:37:39.146",
"maximumPaymentAmount": 1000.00,
"bbanBSB": null,
"bbanAccountNo": null
}
}
Card Payload Explanation
Table below explain the meaning of card
payload:
Payload Field | Description | Details |
---|---|---|
accountHolderName | Account Holder's Name | Show the card holders name for Visa / Mastercard. |
expiryYear | Year of card expiry | Showing last 2 digit of the year of expiry, |
expiryMonth | Month of card expiry | Showing the 2 digit of the month of expiry, |
type | Type of the card | 3 possible value. a) VISA b) MASTER c) AMEX This should display to the customer. |
last4 | Last 4 digit of card number | This should display to the customer. Together with type of card will allows customer to identify the payment method easily. |
first6 | First 6 digit of card number | |
origin | origin of the token | null - VISA, Mastercard and AMEX |
tokenDetails | Details of the network token | An object contains following field.tokenType - type of the tokenfriendlyDisplay - null originalLast4 - Last 4 for the original cardstokenFirst6 - First 6 of the network tokentokenLast4 - Last 4 of the network tokentokenExpiry - Expiry date of the network token, different from the card expiry date. |
tokenized | Boolean flag for network tokenized card | Applicable value: a) true - card is network tokenizedb) false - card is not network tokenized |
Bank Payload Explanation
Table below explain the meaning of bank
payload:
Payload Field | Description | Details |
---|---|---|
accountHolderName | Account Holder's Name | |
last4 | Last 4 digit of bank account number | Integrators should store this and display to the customer to allow customer identify the payment method easily. |
bankNumber | Bank Number of the bank | AU: 6 digit BSB Number NZ: 2 digit bank number Integrators should store this and display to the customer to allow customer identify the payment method easily. |
branchNumber | Branch number of the bank | AU: null NZ: 4 digit branch code |
suffixNumber | Suffix Number of the bank | AU: null NZ: 2 or 3 digit suffix number |
countryCode | Country code of the bank | ISO 3166 country codes |
bankTransferType | Indicates local or international transfer | Applicable value: a) local b) international |
Wallet Payload Explanation
Table below explain the meaning of wallet
payload:
Payload Field | Description | Details |
---|---|---|
accountHolderName | Account Holder's Name | |
accountMobileNumber | Mobile Number that the wallet ties to | This is the full mobile number with country code. Integrators should store this and display to the customer to allow customer identify the payment method easily.. |
type | Type of the wallet. | Integrators should store this and display to the customer to allow customer identify the payment method easily. |
merchantId | Merchant ID of Ezypay | |
walletPaymentProviderId | Account ID tied to the payment provider | This ID is for payment provider identification |
countryCode | Country code of the wallet | ISO 3166 country codes |
## PayTo Payload Explanation
Table below explain the meaning of payTo
payload:
Payload Field | Description | Details |
---|---|---|
accountHolderName | Account Holder's Name | This is the full name used for the customer's bank account. |
accountType | Account Type | This is the type of account that the customer is using for PayTo: BBAN - Bank Account Number ALIA - Alias, a PayID is used |
aliasType | type of the PayID | Showing the type of PayID captured.. EMAL - Email address is used as PayID TELI - Phone number is used as PayID If accountType is not ALIA , this field is null .Integrators should store this and display to the customer to allow customer identify the payment method easily. |
aliasId | Details of the PayID | Depends on aliasType , this field shows the details of the PayID captured.EMAL - Display the email address registered as PayID TELI - Display the phone number registered as PayID If accountType is not ALIA , this field is null .Integrators should store this and display to the customer to allow customer identify the payment method easily. |
merchantId | Ezypay Merchant ID | This is the unique identifier of the merchant when they onboarded Ezypay. |
mandateTypeId | Ezypay Mandate Type ID | This is the unique identifier assigned to the merchant by Ezypay when they have been enabled to use PayTo services. |
mandateStatus | Mandate Status | This is the status code of the mandate. A mandate can have the following status code: - CRTD - CNCD - ACTV - SUSD |
mandateReason | Mandate Status Description | This is explanation of the mandateStatus .- Created = CRTD - Cancelled = CNCD - Active = ACTV - Suspended =SUSD |
mandateId | PayTo Mandate ID | This is a unique identifier used between Ezypay and their banking partner. |
description | Description of the mandate | This description explain the purpose of the mandate |
frequency | Billing frequency of the mandate | Indicates the allowed payment frequency for this mandate. Current available value is ADHO which indicates ad-hoc. |
validityStartDate | Date of mandate creation | Showing the date of PayTo mandate being created in ISO 8601 format. |
maximumPaymentAmount | Maximum amount of a transaction | Maximum allowable amount to be transacted using this mandate. |
bbanBSB | Account Holder's BSB Number | This is the BSB number of the customer's bank account. If accountType is not BBAN , this field is null .Integrators should store this and display to the customer to allow customer identify the payment method easily. |
bbBanAccountNo | Account Holder's Bank Account Number | This is the account number for the customer's bank account. If accountType is not BBAN , this field is null .Integrators should store this and display to the customer to allow customer identify the payment method easily. |
Updated 2 days ago