Payment Vault Object Reference and Response Code
Posted by Diwa del Mundo, Jonathan Francisco, John Lawrence Poklay, Abby Alcantara, Brian Jefferson Tan • Wednesday October 25, 2017 10:14 AM
 

API Object Reference

Card Object

Buyer Object

Contact Object

Billing Address Object

Total Amount Object

Redirect URL Object

Error Object

Error Parameters Object

Error Details Object

Payment Facilitator Object

Subscription Object

Webhook Object

Void Object

Refund Object

Payment Object

 

Card Object

Field Description Length Attribute Mandatory
number Valid card number of Visa or MasterCard 12-16 Numeric Yes
expMonth Expiry month of card 2 Numeric Yes
expYear Expiry year of card 4 Numeric Yes
cvc CVC/CVV of card 3-4 Numeric Yes

Buyer Object

Field Description Length Attribute Mandatory
firstName First name of buyer 1-50 Alphanumeric No
middleName Middle name of buyer 1-50 Alphanumeric No
lastName Last name of buyer 1-50 Alphanumeric No
sex Sex of buyer 1 F or M only No
birthday Birth date of buyer 10 YYYY-MM-DD No
contact Contact details of buyer - See Contact Object No
billingAddress Billing address of buyer - See Billing Address Object No

*Buyer Object when provided must have at least one populated field

 

Contact Object

Field Description Length Attribute Mandatory
phone Phone number of buyer 1-20 Numeric with + - ( ) No
email Valid email address of buyer 5-254 Alphanumeric No

Billing Address Object

Field Description Length Attribute Mandatory
line1 Building/House number and street of buyer's address 1-100 Alphanumeric No
line2 Subdivision and Barangay of buyer's address 1-100 Alphanumeric No
city City address of buyer 1-100 Alphanumeric No
state State/Province of buyer's address 1-100 Alphanumeric No
zipCode Zip code of buyer's address 1-20 Numeric with ~ - No
countryCode Country code based from ISO 3166-2 2 Alphabet No

Total Amount Object

Field Description Length Attribute Mandatory
amount Payment amount to be charged to the card 1-9 Numeric with (.) Yes
currency Payment currency based from ISO 4217, allowed for merchant 3 Alphabet Yes

Redirect URL Object

Field Description Length Attribute Mandatory
success Redirect URL after a successful 3DS payment 1-2082 URL No
failure Redirect URL after a failed 3DS payment 1-2082 URL No
cancel Redirect URL after a cancelled 3DS payment 1-2082 URL No

Error Object

Field Description Length Attribute Mandatory
error Error response code from Paymaya Payments API 1-10 Alphanumeric Yes
message Description of error 1-50 Alphanumeric Yes
parameters Details of Paymaya Payments API error - See Error Parameters Object No
details Details of non-Paymaya Payments API error - See Error Details Object No

Error Parameter Object

Field Description Length Attribute Mandatory
field Field that did not pass validation 1-20 Alphanumeric Yes
description Validation rule for the field 1-50 Alphanumeric Yes

Error Details Object

Field Description Length Attribute Mandatory
responseCode Service error code 1-50 Alphanumeric Yes
responseDescription Service error description 1-50 Alphanumeric Yes
requestReferenceNumber Service error RRN 1-50 Alphanumeric No

Payment Facilitator Object

Field Description Length Attribute Mandatory
smi Sub-merchant ID assigned by the payment facilitator or their acquirer 1-15 Alphanumeric Yes
smn Name of sub-merchant 1-9 Alphanumeric Yes
mci Sub-merchant City 1-13 Alphanumeric Yes
mpc 3-digit numeric country code of the sub-merchant 3 Numeric Yes
mco Alphabetic 3-character country code of the sub-merchant 3 Alphabet Yes
mst Sub-merchant state 2-3 Alphabet Yes, if MPC is 840

Subscriptions Object

Field Description Length Attribute Mandatory
description A string of subscription description 1-255 Alphanumeric Yes
interval Measure of occurence for the recurring payment - DAY, MONTH, YEAR Yes
intervalCount Number of interval for the recurring payment 1-365 Numeric Yes
startDate Start date of charging payment for the subscription - Date Yes
endDate End date of charging payment for the subscription - Date No
totalAmount Amount that will be charged for the subscription payment - See Total Amount Object Yes
metedata Sub-merchant details - See  Payment Facilitator Object Yes, if merchant is a Payment Facilitator

Webhook Object

Field Desription Length Attribute Mandatory
name Event of the webhook 1-50 3DS_PAYMENT_SUCCESS,3DS_PAYMENT_FAILURE,RECURRING_PAYMENT_SUCCESS ,RECURRING_PAYMENT_FAILURE Yes
callbackUrl Merchant's URL that will be called for the event 1-2000 URL Yes

Void Object

Field Description Length Attribute Mandatory
reason A string for reason of void 1-255 Alphanumeric Yes

Refund Object

Field Description Length Attribute Mandatory
reason A string for reason of refund 1-255 Alphanumeric Yes
totalAmount Amount to be refunded from the payment - See Total Amount Object Yes

Payment Object

Field Description Length Attribute Mandatory
paymentTokenId The token to use for the payment - Alphanumeric Yes
totalAmount Amount to charge - See Total Amount Object Yes
buyer Buyer's details - See Buyer Object No
requestReferenceNumber A merchant recognized identifier for the payment 0-36 Alphanumeric No
redirectUrl A collection of URLs to control the payment flow after 3-D Secure authentication (if applicable) - See Redirect Object No

API Response Code

HTTP Status Code Message Description
400 2553 Missing/invalid Parameters A required parameter is missing or has a null/empty/invalid value. Field and description will be shown in parameters object.
400 PY0001 A problem is encountered. Please contact your system administrator Generic system error. Please contact us if you encounter this error.
400 PY0002 Card is expired Card is already expired based from expMonth and expYear.
400 PY0007 Invalid token status Card is either expired, in use or used.
400 PY0008 Token is invalid Payment token does not exist.
400 PY0009 Payment does not exist Payment ID does not exist.
408 PY0013 A problem is encountered. Please contact your system administrator Generic system error. Please contact us if you encounter this error.
400 PY0014 A problem is encountered. Please contact your system administrator Generic system error. Please contact us if you encounter this error.
408 PY0015 A problem is encountered. Please contact your system administrator Generic system error. Please contact us if you encounter this error.
400 PY0016 A problem is encountered. Please contact your system administrator Generic system error. Please contact us if you encounter this error.
400 PY0017 Merchant not found Merchant does not exist.
401 PY0019 Forbidden Merchant is not allowed to use the resource. 
400 PY0021 Failed to add customer Generic error for failed addition of customer.
400 PY0023 Customer does not exist Customer ID does not exist.
400 PY0024 Failed to delete customer Generic error for failed deletion of customer.
400 PY0025 Failed to update customer details Generic error for failed update of customer.
400 PY0026 Failed to update card details Generic error for failed update of card.
400 PY0027 Card does not exist Card does not exist.
400 PY0029 No card found for customer No active card linked to customer.
400 PY0030 Invalid card token status Card status is unverified, verifying or verifying failed.
400 PY0035 Failed to add card to customer Generic error for failed addition of customer.
400 PY0036 Card is not supported Card is not Visa or MasterCard.
400 PY0037 Currency is not supported Currency is not allowed for merchant.
400 PY0038 Webhook does not exist Webhook does not exist in Webhooks.
400 PY0039 Webhook already exists  Duplicate webhook in Webhooks
408 PY0040 A problem is encountered. Please contact your system administrator Generic system error. Please contact us if you encounter this error.
400 PY0041 A problem is encountered. Please contact your system administrator Generic system error. Please contact us if you encounter this error.
400 PY0043 Card already exists Linking duplicate card token to a customer.
400 PY0046 Refund does not exist Refund ID does not exist
400 PY0047 Payment is ineligible for refund Refund time is not yet beyond 6PM or payment status not valid for refund.
400 PY0048 Requested refund amount is greater than the original amount Payment has insufficient remaining amount for refund.
400  PY0049 Subscription does not exist Subcription does not exist for card 
400 PY0055 Payment is not available for void Payment status is not valid for void