PAYOMO API
Introduction
The PAYOMO API allows customeres to purchase items with their credit cards and merchants to securely process process these transactions securely. Customers can purchase virtual cards for their transactions to provide additional security while shopping online.
The PAYOMO API is targeted toward the travel and ecommerce industries.
Current Version
1.0
API URI
http://prod.payomo.com
Access Token
An access token can be obtained by POSTing the client_id and client_secret url (encoded) along with the grant_type as "client_credentials".
Header
| Field | Value |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Body (urlencoded)
| Field | Value |
|---|---|
| grant_type | client_credentials |
| client_id | ekncjhdurkm8923hfcknkru4 |
| client_secret | nakjf720fnxlnh |
Request
curl --location --request POST "https://prod.payomo.com/api/v1/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials&client_id=ekncjhdurkm8923hfcknkru4&client_secret=nakjf720fnxlnh"
var settings = {
"url": "https://prod.payomo.com/api/v1/oauth2/token",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
"data": {
"grant_type": "client_credentials",
"client_id": "ekncjhdurkm8923hfcknkru4",
"client_secret": "nakjf720fnxlnh"
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response
status :200 ok
Refresh Your Token
When your token expires, request a new token.
Payments
The PAYOMO API URL is:
`http://prod.payomo.com`
The PAYOMO API has the following resources. The table shows the functionality provided by the PAYOMO API and links to the related resources to invoke or call.
| Resource Name | Description | Endpoint |
|---|---|---|
| API Health Check | Obtain the health of the PAYOMO API. | https://prod.payomo.com/api/v1/card/health |
| Auth | Approves a credit card for a specific amount and holds the funds to be processed. | https://prod.payomo.com/api/v1/card/auth |
| Capture | Capturing an existing credit card authorization and transfers the funds from the credit card holder to the merchant. | https://prod.payomo.com/api/v1/card/authsettle |
| Sale | Performs authorization and capture of funds from a credit card together | https://prod.payomo.com/api/v1/card/sale |
| Void | Voids a credit card authorization. | https://prod.payomo.com/api/v1/card/void |
| Credit | Credits the funds back to the credit card holder. | https://prod.payomo.com/api/v1/card/credit |
| Status | Obtain the status of a transaction that was performed on a credit card. | https://prod.payomo.com/api/v1/card/txnstatus |
| BIN | Retrieves the bank identification number (BIN), the initial four to six numbers on a credit card. | https://prod.payomo.com/api/v1/card/bininfo |
| Purchase VCard | Allows a customer to buy a virtual card to use for transactions instead of a credit card. | https://prod.payomo.com/api/v1/virtualcard/purchase |
API Health check
GETs the health of the PAYOMO API. A 200 response means that the API is up and running.
URL for the API
https://prod.payomo.com/api/v1/card/health
Request Sample
curl --location --request GET "https://prod.payomo.com/api/v1/card/health"
var settings = {
"url": "https://prod.payomo.com/api/v1/card/health",
"method": "get",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"transaction":{"merchantReference":"test","amount":1,"currency":"USD","transactionType":"AIR"},"customer":{"sourceApp":"API"},"creditCard":{"cardHolderName":"Card holder name","cardType":"VI","expiryDate":"0119","cardNumber":"4111111111111111","cvv":"402","street1":"Street name","city":"City name","state":"2 letter State code","countryCode":"2 letter Country code","zipCode":"zipcode","email":"test@payomo.com","phoneNumber":"1234567890"},"cardStatement":{"merchantReference":"test","statementDescriptor":"Text to appear on credit card statement","originLocationCode":"SRC","destinationLocationCode":"DST","departureDate":"20200131"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response Sample
200 OK
Authorize credit card
Approves a credit card for a specific amount and holds the funds to be processed
This resource uses the POST action.
URL for the API
https://prod.payomo.com/api/v1/card/auth
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | request token |
json request
{
"transaction": {
"merchantReference": "test",
"amount": 1.0,
"currency": "USD",
"transactionType": "AIR"
},
"customer": {
"sourceApp": "API"
},
"creditCard": {
"cardHolderName": "Card holder name",
"cardType": "VI",
"expiryDate": "0119",
"cardNumber": "4111111111111111",
"cvv": "402",
"street1": "Street name",
"city": "City name",
"state": "2 letter State code",
"countryCode": "2 letter Country code",
"zipCode": "zipcode",
"email": "test@payomo.com",
"phoneNumber": "1234567890"
},
"cardStatement": {
"merchantReference": "test",
"statementDescriptor" : "Text to appear on credit card statement",
"originLocationCode": "SRC",
"destinationLocationCode": "DST",
"departureDate": "20200131"
}
}
Parameters
| Field | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
creditCard.expiryDate |
string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
creditCard.street1 |
string Payment card billing street address as it appears on the credit card issuer’s records. |
creditCard.city |
string Payment card billing city. |
creditCard. state |
string State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
creditCard.countryCode |
string Payment card billing country. Use the two-character ISO Standard Country Codes. |
creditCard.zipCode |
string Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
creditCard.email |
string Customer's email address, including the full domain name. |
creditCard.phoneNumber |
string Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
referenceTransaction.referenceTxnId(*) |
string Transaction reference of the authorization / sale. |
Request Sample
curl --location --request POST "http://prod.payomo.com/api/v1/card/auth" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer hjgsfjndsolsdd623bhvnclasjfkwq92nsd" \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1.0,
\"currency\": \"USD\",
\"transactionType\": \"AIR\"
},
\"customer\": {
\"sourceApp\": \"API\"
},
\"creditCard\": {
\"cardHolderName\": \"Card holder name\",
\"cardType\": \"VI\",
\"expiryDate\": \"123\",
\"cardNumber\": \"4111111111111111\",
\"cvv\": \"123\",
\"street1\": \"Street address\",
\"city\": \"City name\",
\"state\": \"2-letter state code\",
\"countryCode\": \"2-letter country code\",
\"zipCode\": \"zipcode\",
\"email\": \"test@payomo.com\",
\"phoneNumber\": \"1234567890\"
},
\"cardStatement\": {
\"statementDescriptor\" : \"Descriptor\"
\"merchantReference\": \"test\",
\"airlineName\": \"2-letter airline name\",
\"originLocationCode\": \"SRC\",
\"destinationLocationCode\": \"DST\",
\"departureDate\": \"20200131\"
}
}"
var settings = {
"url": "http://localhost:7000/masterdata/pcccredentials/CityTravel",
"method": "PUT",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"transaction":{"merchantReference":"test","amount":1,"currency":"USD","transactionType":"AIR"},"customer":{"sourceApp":"API"},"creditCard":{"cardHolderName":"Card holder name","cardType":"VI","expiryDate":"0119","cardNumber":"4111111111111111","cvv":"402","street1":"Street name","city":"City name","state":"2 letter State code","countryCode":"2 letter Country code","zipCode":"zipcode","email":"test@payomo.com","phoneNumber":"1234567890"},"cardStatement":{"merchantReference":"test","statementDescriptor":"Text to appear on credit card statement","originLocationCode":"SRC","destinationLocationCode":"DST","departureDate":"20200131"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response Sample
{
"code": 200,
"message": "APPROVED",
"messageDescription": null,
"merchantReference": "test",
"pmTransactionReference": "Qnjflksaubc7weerjk",
"transactionType": "auth",
"amount": 1.0,
"authorizationCode": "123456",
"transactionDate": "31122019",
"transactionTime": "13338",
"cardNumber": "486545******1025"
}
Capture authorization
Cature an existing authorization. This transfers the funds from the credit card holder account to the merchant. This resource uses the POST action.
URL for the API
https://prod.payomo.com/api/v1/card/authsettle
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | access request token |
json request
{
"transaction": {
"merchantReference": "test",
"amount": 1.0,
"currency": "USD"
},
"customer": {
"sourceApp": "API"
},
"creditCard": {
"cardHolderName": "Card holder name",
"cardType": "VI",
"expiryDate": "0119",
"cardNumber": "4111111111111111",
"cvv": "123",
"street1": "Street address",
"countryCode": "2-letter country code",
"city": "City name",
"state": "2-letter state code",
"zipCode": "zipcode",
"email": "test@payomo.com",
"phoneNumber": "1234567890"
},
"cardStatement": {
"merchantReference": "test",
"originLocationCode": "SRC",
"destinationLocationCode": "DST",
"departureDate": "20191231"
},
"referenceTransaction": {
"referenceTxnId": "KabsjsdopjJYas"
}
}
Parameters
| Field | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
creditCard.expiryDate |
string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
creditCard.street1 |
string Payment card billing street address as it appears on the credit card issuer’s records. |
creditCard.city |
string Payment card billing city. |
creditCard. state |
string State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
creditCard.countryCode |
string Payment card billing country. Use the two-character ISO Standard Country Codes. |
creditCard.zipCode |
string Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
creditCard.email |
string Customer's email address, including the full domain name. |
creditCard.phoneNumber |
string Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
referenceTransaction.referenceTxnId(*) |
string Transaction reference of the authorization / sale. |
Request Sample
curl --location --request POST "https://prod.payomo.com/api/v1/card/authsettle" \
--header "Content-Type: application/json" \
--header "Authorization: " \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1.0,
\"currency\": \"USD\"
},
\"customer\": {
\"sourceApp\": \"API\"
},
\"creditCard\": {
\"cardHolderName\": \"Card holder name\",
\"cardType\": \"VI\",
\"expiryDate\": \"0919\",
\"cardNumber\": \"4111111111111111\",
\"cvv\": \"123\",
\"street1\": \"Street address\",
\"countryCode\" : \"2-letter country code\",
\"city\": \"City name\",
\"state\": \"2-letter state code\",
\"zipCode\": \"zipcode\",
\"email\": \"test@payomo.com\",
\"phoneNumber\": \"1234567890\"
},
\"cardStatement\": {
\"merchantReference\": \"test\",
\"airlineName\": \"2-letter airline code\",
\"originLocationCode\": \"SRC\",
\"destinationLocationCode\": \"DST\",
\"departureDate\": \"20191231\"
},
\"referenceTransaction\": {
\"referenceTxnId\": \"KabsjsdopjJYas\"
}
}"
var settings = {
"url": "https://prod.payomo.com/api/v1/card/authsettle",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"transaction":{"merchantReference":"test","amount":1,"currency":"USD"},"customer":{"sourceApp":"API"},"creditCard":{"cardHolderName":"Card holder name","cardType":"VI","expiryDate":"0119","cardNumber":"4111111111111111","cvv":"123","street1":"Street address","countryCode":"2-letter country code","city":"City name","state":"2-letter state code","zipCode":"zipcode","email":"test@payomo.com","phoneNumber":"1234567890"},"cardStatement":{"merchantReference":"test","originLocationCode":"SRC","destinationLocationCode":"DST","departureDate":"20191231"},"referenceTransaction":{"referenceTxnId":"KabsjsdopjJYas"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response Sample
{
"code": 200,
"message": "APPROVED",
"messageDescription": null,
"merchantReference": "test",
"pmTransactionReference": "yJwZDONHjB",
"transactionType": "authsettle",
"amount": 1.0,
"authorizationCode": "1234567890",
"transactionDate": null,
"transactionTime": null,
"cardNumber": "411111******1111"
}
Sale
Create a sale on a credit card. This transfers the funds from the credit card holder account to the merchant. It is a combination of authorization and capture. This resource uses the POST action.
URL for the API
https://prod.payomo.com/api/v1/card/sale
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | access request token |
json request
{
"transaction": {
"merchantReference": "test",
"amount": 1.0,
"currency": "USD"
},
"customer": {
"sourceApp": "API"
},
"creditCard": {
"cardHolderName": "Card holder name",
"cardType": "VI",
"expiryDate": "0119",
"cardNumber": "4111111111111111",
"cvv": "123",
"street1": "Street address",
"countryCode": "2-letter country code",
"city": "City name",
"state": "2-letter state code",
"zipCode": "zipcode",
"email": "test@payomo.com",
"phoneNumber": "1234567890"
},
"cardStatement": {
"merchantReference": "test",
"originLocationCode": "SRC",
"destinationLocationCode": "DST",
"departureDate": "20191231"
},
}
Parameters
| Field | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
creditCard.expiryDate |
string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
creditCard.street1 |
string Payment card billing street address as it appears on the credit card issuer’s records. |
creditCard.city |
string Payment card billing city. |
creditCard. state |
string State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
creditCard.countryCode |
string Payment card billing country. Use the two-character ISO Standard Country Codes. |
creditCard.zipCode |
string Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
creditCard.email |
string Customer's email address, including the full domain name. |
creditCard.phoneNumber |
string Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
referenceTransaction.referenceTxnId(*) |
string Transaction reference of the authorization / sale. |
Request Sample
curl --location --request POST "https://prod.payomo.com/api/v1/card/sale" \
--header "Content-Type: application/json" \
--header "Authorization: " \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1.0,
\"currency\": \"USD\"
},
\"customer\": {
\"sourceApp\": \"API\"
},
\"creditCard\": {
\"cardHolderName\": \"Card holder name\",
\"cardType\": \"VI\",
\"expiryDate\": \"0919\",
\"cardNumber\": \"4111111111111111\",
\"cvv\": \"123\",
\"street1\": \"Street address\",
\"countryCode\" : \"2-letter country code\",
\"city\": \"City name\",
\"state\": \"2-letter state code\",
\"zipCode\": \"zipcode\",
\"email\": \"test@payomo.com\",
\"phoneNumber\": \"1234567890\"
},
\"cardStatement\": {
\"merchantReference\": \"test\",
\"airlineName\": \"2-letter airline code\",
\"originLocationCode\": \"SRC\",
\"destinationLocationCode\": \"DST\",
\"departureDate\": \"20191231\"
}
}"
var settings = {
"url": "https://prod.payomo.com/api/v1/card/sale",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"transaction":{"merchantReference":"test","amount":1,"currency":"USD"},"customer":{"sourceApp":"API"},"creditCard":{"cardHolderName":"Card holder name","cardType":"VI","expiryDate":"0119","cardNumber":"4111111111111111","cvv":"123","street1":"Street address","countryCode":"2-letter country code","city":"City name","state":"2-letter state code","zipCode":"zipcode","email":"test@payomo.com","phoneNumber":"1234567890"},"cardStatement":{"merchantReference":"test","originLocationCode":"SRC","destinationLocationCode":"DST","departureDate":"20191231"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response Sample
{
"code": 200,
"message": "APPROVED",
"messageDescription": null,
"merchantReference": "test",
"pmTransactionReference": "yJwZDONHjB",
"transactionType": "sale",
"amount": 1.0,
"authorizationCode": "1234567890",
"transactionDate": null,
"transactionTime": null,
"cardNumber": "411111******1111"
}
Void
Voids a credit card authorization/ sale. This resource uses the POST action.
URL for the API
https://prod.payomo.com/api/v1/card/void
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | access request token |
json request
{
"transaction": {
"merchantReference": "test",
"amount": 1.0,
"currency": "USD"
},
"customer": {
"sourceApp": "API"
},
"creditCard": {
"cardHolderName": "Card holder name",
"cardType": "VI",
"expiryDate": "0119",
"cardNumber": "4111111111111111",
"cvv": "123",
"street1": "Street address",
"countryCode": "2-letter country code",
"city": "City name",
"state": "2-letter state code",
"zipCode": "zipcode",
"email": "test@payomo.com",
"phoneNumber": "1234657890"
},
"cardStatement": {
"merchantReference": "test",
"airlineName": "2-letter airline code",
"originLocationCode": "SRC",
"destinationLocationCode": "DST",
"departureDate": "20191231"
},
"referenceTransaction": {
"referenceTxnId": "RUfKTbeqnsfklWRTsafdVY"
}
}
Parameters
| Field | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
creditCard.expiryDate |
string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
creditCard.street1 |
string Payment card billing street address as it appears on the credit card issuer’s records. |
creditCard.city |
string Payment card billing city. |
creditCard. state |
string State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
creditCard.countryCode |
string Payment card billing country. Use the two-character ISO Standard Country Codes. |
creditCard.zipCode |
string Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
creditCard.email |
string Customer's email address, including the full domain name. |
creditCard.phoneNumber |
string Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
referenceTransaction.referenceTxnId(*) |
string Transaction reference of the authorization / sale. |
Request Sample
curl --location --request POST "https://prod.payomo.com/api/v1/card/void" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer JasjlVSduiuBYTUVasyofnN" \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1.0,
\"currency\": \"USD\"
},
\"customer\": {
\"sourceApp\": \"API\"
},
\"creditCard\": {
\"cardHolderName\": \"Card holder name\",
\"cardType\": \"VI\",
\"expiryDate\": \"0919\",
\"cardNumber\": \"4111111111111111\",
\"cvv\": \"123\",
\"street1\": \"Street address\",
\"countryCode\": \"2-letter country code\",
\"city\": \"City name\",
\"state\": \"2-letter state code\",
\"zipCode\": \"zipcode\",
\"email\": \"test@payomo.com\",
\"phoneNumber\": \"1234567890\"
},
\"cardStatement\": {
\"merchantReference\": \"test\",
\"airlineName\": \"2-letter airline code\",
\"originLocationCode\": \"SRC\",
\"destinationLocationCode\": \"DST\",
\"departureDate\": \"20191231\"
},
\"referenceTransaction\": {
\"referenceTxnId\": \"RUfKTbeqnsfklWRTsafdVY\"
}
}"
var settings = {
"url": "https://prod.payomo.com/api/v1/card/void",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"transaction":{"merchantReference":"test","amount":1,"currency":"USD"},"customer":{"sourceApp":"API"},"creditCard":{"cardHolderName":"Card holder name","cardType":"VI","expiryDate":"0119","cardNumber":"4111111111111111","cvv":"123","street1":"Street address","countryCode":"2-letter country code","city":"City name","state":"2-letter state code","zipCode":"zipcode","email":"test@payomo.com","phoneNumber":"1234657890"},"cardStatement":{"merchantReference":"test","airlineName":"2-letter airline code","originLocationCode":"SRC","destinationLocationCode":"DST","departureDate":"20191231"},"referenceTransaction":{"referenceTxnId":"RUfKTbeqnsfklWRTsafdVY"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response Sample
{
"code": 200,
"message": "APPROVED",
"messageDescription": null,
"merchantReference": "test",
"pmTransactionReference": "khgxknLFEp",
"transactionType": "void",
"amount": 1.0,
"authorizationCode": "123456",
"transactionDate": null,
"transactionTime": null,
"cardNumber": "411111******1111"
}
Credit
Credits the funds back to the credit card holder. This resource uses the POST action.
URL for the API
<a href='https://prod.payomo.com/api/v1/card/credit'>https://prod.payomo.com/api/v1/card/credit</a>
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | access request token |
json request
{
"transaction": {
"merchantReference": "test",
"amount": 1.0,
"currency": "USD"
},
"customer": {
"sourceApp": "API"
},
"creditCard": {
"cardHolderName": "Card holder name",
"cardType": "VI",
"expiryDate": "0123",
"cardNumber": "4111111111111111",
"cvv": "123",
"street1": "Street address",
"countryCode": "2-letter country code",
"city": "City name",
"state": "2-letter state code",
"zipCode": "zipcode",
"email": "test@payomo.com",
"phoneNumber": "1234567890"
},
"cardStatement": {
"merchantReference": "test",
"statementDescriptor" : "Descriptor",
"airlineName": "2-letter airline code",
"originLocationCode": "SRC",
"destinationLocationCode": "DST",
"departureDate": "20200131"
},
"referenceTransaction": {
"referenceTxnId": "ghRianfgpasUYopwje"
}
}
Parameters
| Field | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
customer.customerId(-) |
string PAYOMO API account ID. |
customer.email (-) |
string PAYOMO API user email address. |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
creditCard.expiryDate |
string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
billingAddress.street1 |
string -Payment card billing street address as it appears on the credit card issuer’s records. |
billingAddress.city |
string -Payment card billing city. |
billingAddress. state</> |
string -State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
billingAddress.countryCode |
string -Payment card billing country. Use the two-character ISO Standard Country Codes. |
billingAddress.zipCode |
string-Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
billingAddress.email |
string -Customer's email address, including the full domain name. |
billingAddress.phoneNumber |
string -Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
flightSegments |
string Segment number information of the order to show on statement Descriptor Segment number information of the order to show on statement Descriptor |
flightSegments.fromLocationCode |
string the location code from where your start |
flightSegments.toLocationCode |
string the location code to where your destination |
flightSegments.carrier |
string airlines code we travel |
flightSegments.bookingClass |
string type of booking class which we book |
flightSegments.stopOver |
int no of stops inbetween |
| referenceTransaction.referenceTxnId | string Transaction reference of the authorization capture/ sale. |
Request Sample
curl --location --request POST "https://prod.payomo.com/api/v1/card/credit" \
--header "Content-Type: application/json" \
--header "Authorization: " \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1.0,
\"currency\": \"USD\"
},
\"customer\": {
\"sourceApp\": \"API\"
},
\"creditCard\": {
\"cardHolderName\": \"Card holder name\",
\"cardType\": \"VI\",
\"expiryDate\": \"0119\",
\"cardNumber\": \"4111111111111111\",
\"cvv\": \"123\",
\"street1\": \"Street address\",
\"countryCode\": \"2-letter country code\",
\"city\": \"City name\",
\"state\": \"2-letter state code\",
\"zipCode\": \"zipcode\",
\"email\": \"test@payomo.com\",
\"phoneNumber\": \"1234567890\"
},
\"cardStatement\": {
\"merchantReference\": \"test\",
\"airlineName\": \"2-letter airline code\",
\"originLocationCode\": \"SRC\",
\"destinationLocationCode\": \"DST\",
\"departureDate\": \"20191231\"
},
\"referenceTransaction\": {
\"referenceTxnId\": \"ghRianfgpasUYopwje\"
}
}"
var settings = {
"url": "http://localhost:7000/masterdata/pcccredentials/CityTravel",
"method": "PUT",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"transaction":{"merchantReference":"test","amount":1,"currency":"USD"},"customer":{"sourceApp":"API"},"creditCard":{"cardHolderName":"Card holder name","cardType":"VI","expiryDate":"0123","cardNumber":"4111111111111111","cvv":"123","street1":"Street address","countryCode":"2-letter country code","city":"City name","state":"2-letter state code","zipCode":"zipcode","email":"test@payomo.com","phoneNumber":"1234567890"},"cardStatement":{"merchantReference":"test","statementDescriptor":"Descriptor","airlineName":"2-letter airline code","originLocationCode":"SRC","destinationLocationCode":"DST","departureDate":"20200131"},"referenceTransaction":{"referenceTxnId":"ghRianfgpasUYopwje"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response Sample
{
"code": 200,
"message": "APPROVED",
"messageDescription": null,
"merchantReference": "test",
"pmTransactionReference": "kabnBNWwebBUjk",
"transactionType": "credit",
"amount": 1.0,
"authorizationCode": "123456",
"transactionDate": null,
"transactionTime": null,
"cardNumber": "411111******1111"
}
Obtain transaction status
This API obtains the status of a transaction done on a credit card. This resource uses the POST action.
URL for the API
https://prod.payomo.com/api/v1/card/txnstatus
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | access request token |
json request
{
"customer": {
"sourceApp": "API"
},
"referenceTransaction": {
"referenceTxnId": "HbEsBBoUHp"
}
}
Parameters
| Field | Description |
|---|---|
customer.customerId(-) |
string PAYOMO API account ID. |
customer.sourceApp(-) |
string Accepts "API". |
customer.email (-) |
string PAYOMO API user email address. |
customer.ipAddress(-) |
string IP address from where the PAYOMO API is being accessed. |
referenceTransaction |
referenceTxnId |
Request Sample
curl --location --request POST "https://prod.payomo.com/api/v1/card/txnstatus" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YbslGHbdsfonvuwnvofaiafoRTVHJ6vsa" \
--data "{
\"customer\": {
\"sourceApp\": \"API\"
},
\"referenceTransaction\": {
\"referenceTxnId\": \"HbEsBBoUHp\"
}
}"
var settings = {
"url": "http://localhost:7000/masterdata/pcccredentials/CityTravel",
"method": "PUT",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"customer":{"sourceApp":"API"},"referenceTransaction":{"referenceTxnId":"HbEsBBoUHp"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
})
Response Sample
status: 200 ok
BIN
Retrieves the bank identification number (BIN), the initial four to six numbers on a credit card. This resource uses the POST action.
URL for the API
https://prod.payomo.com/api/v1/card/bininfo
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | access request token |
json request
{
"transaction": {
"merchantReference": "test",
"amount": 1,
"currency": "USD"
},
"customer": {
"sourceApp": "API",
"ipAddress": "127.0.0.1"
},
"creditCard": {
"cardNumber": "4111111111111111"
}
}
Parameters
| Field | Description |
|---|---|
transaction.merchantReference(*) |
string Unique reference of the transaction. |
transaction.amount (*) |
double Funds to be loaded on the virtual card. |
transaction.currency (*) |
string Montary system of the funds loaded on the virtual card. Accepts USD/ CAD |
transaction.transactionType(*) |
string Accepts "AIR". |
customer.customerId(-) |
string PAYOMO API account ID. |
customer.sourceApp(-) |
string Accepts "API". |
customer.email (-) |
string PAYOMO API user email address. |
customer.ipAddress(-) |
string IP address from where the PAYOMO API is being accessed. |
creditCard.cardNumber(*) |
string Credit card number. |
Request Sample
curl --location --request POST "https://prod.payomo.com/api/v1/card/bininfo" \
--header "Content-Type: application/json" \
--header "Authorization: " \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1,
\"currency\": \"USD\"
},
\"customer\": {
\"sourceApp\": \"API\",
\"ipAddress\": \"127.0.0.1\"
},
\"creditCard\": {
\"cardNumber\": \"4111111111111111\"
}
}"
var settings = {
"url": "http://localhost:7000/masterdata/pcccredentials/CityTravel",
"method": "PUT",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"transaction":{"merchantReference":"test","amount":1,"currency":"USD"},"customer":{"sourceApp":"API","ipAddress":"127.0.0.1"},"creditCard":{"cardNumber":"4111111111111111"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
Response Sample
{
"cardType": "VISA",
"cardSubType": "DEBIT",
"cardProductCategory": "Visa",
"issuerCountry": "US",
"issuerCountryNumericCode": "840",
"issuerName": "BANK NAME",
"issuerPhoneNumber": "1-800-000-0000"
}
Virtual card
Purchase
Allows a customer to buy a virtual card from PAYOMO for further usage. Every virtual card has a uniquely generated card number. This resource uses the POST action.
URL for the API
https://prod.payomo.com/api/v1/virtualcard/purchase
Header
| Field | Value |
|---|---|
| Content-Type | application/json |
| Authorization | access token |
json request
{
"transaction": {
"merchantReference" :"test",
"amount": 1.0,
"currency": "USD",
"transactionType": "AIR"
},
"customer": {
"sourceApp": "API",
"email" : "test@payomo.com",
"customerId" : "21324C3A-A8CA-4A61-9006-75F741A12488"
},
"vcardDetails" : {
"airlineCode" : "UA",
"requestType" : "NEW"
}
}
Parameters
| Field | Description |
|---|---|
transaction.merchantReference(*) |
string Unique reference of the transaction. |
transaction.amount (*) |
double Funds to be loaded on the virtual card. |
transaction.currency (*) |
string Montary system of the funds loaded on the virtual card. Accepts USD/ CAD |
transaction.transactionType(*) |
string Accepts "AIR". |
customer.customerID(-) |
string PAYOMO API account ID. |
customer.sourceApp(-) |
string Accepts "API". |
customer.email (-) |
string PAYOMO API user email address. |
customer.ipAddress(-) |
string IP address from where the PAYOMO API is being accessed. |
vcardDetails.airlineCode(*) |
integer A unique two-letter code that identifies the airline. |
vcardDetails.requestType (*) |
integer Virtual card request type. Accepts NEW/UPDATE. |
Request Sample
{
"transaction": {
"merchantReference" :"test",
"amount": 1.0,
"currency": "USD",
"transactionType": "AIR"
},
"customer": {
"sourceApp": "API",
"email" : "test@payomo.com",
"customerId" : "21324C3A-A8CA-4A61-9006-75F741A12488"
},
"vcardDetails" : {
"airlineCode" : "UA",
"requestType" : "NEW"
}
}
Response Sample
{
"virtualCardNumber": "4111111111111111",
"expiryDate": "0119",
"securityCode": "123"
}
Smart script
Widget
payomo customizable widget templates for different environments in vertical and horizontal view
Widget Set up
Overview:
Our Widget UI is a complete, ready-made payment UI that offers a quick and easy way to securely accept payments. The UI includes a card entry form and, if enabled, PayPal, Apple Pay, and Google Pay buttons. When a user successfully completes the UI, your client code obtains a payment token details for use on your server.
Configuration:
Setup:
Below is simple snippet for Html script tag
<script src="https://dfpscript.payomo.com/api/v1/smartscript/{accountId}"></script>
Widget is available directly from our servers, which you can include on your site as a script tag or download the file and save it locally.
Callbacks
payomo.widget.create({ /* options */ }, callback);
This adds a global payomo object which includes widget.
Code snippet in Html
<head>
<meta charset="utf-8">
<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
<script src="https://dfpscript.payomo.com/api/v1/smartscript/{accountId}"></script>
</head>
<body>
<div id="widgetDiv"></div>
<script>
var payObj={
selector:"widgetDiv",
payElementId:"widget-pay-button",
finalAmount:"20.1",
countryCode: 'US',
currencyCode: 'USD'
};
payomo.init(function(){
payomo.widget.create(payObj,function(widgetInstance){
console.log("widget created")
//bind click event
$( "#"+payObj.payElementId ).click(function() {
widgetInstance.submitPayment(function(payload){
//get payment details from payload and form auth or sale request
//then call auth or sale method
});
});
});
});
</script>
</body>
Client-side Implementation :
To get started, you will need an account id, a container where Drop-in will appear, and a pay button. When loaded, the UI will appear in the container. Configure your pay button to call submit payment to retrieve the payment details object, including the payment tokens. From there, you can submit the payment details to your server in whichever way you see fit.
Google pay
var payObj = {
selector: "widgetDiv",
payElementId: "widget-pay-button",
finalAmount: "20.1",
countryCode: 'US',
currencyCode: 'USD',
googlePayMerchantId: ”12345” // Production Google pay merchant id
};
payomo.init(function () {
payomo.widget.create(payObj, function (widgetInstance) {
console.log("widget created")
//bind click event
$("#" + payObj.payElementId).click(function () {
widgetInstance.submitPayment(function (payload) {
//google pay
var paymentToken = payload.paymentToken;
var paymentType = payload.selectedPaymentMethod;
//pass above details in auth request and call payment auth method for Auth transaction
});
});
});
});
Before including Google Pay in widget, complete the steps outlined in the Google Pay configuration guide. Once you are configured to use Google Pay, include a googlePay property in your widget create call to render a Google Pay option.
If Google Pay is not supported by the customer's browser, then the option to select Google Pay as widget will not appear.
See Google's developer documentation on testing browser compatibility for more information.
The googlePay object requires a merchantId provided by Google (when in production) within pay object.
Auth request for Googlepay
{
"transaction":{
"merchantReference":"test",
"amount":1.11,
"currency":"USD",
"transactionType":"AIR"
},
"customer":{
"customerId": {acccountId},
"sourceApp":"API",
"ipAddress":"127.0.0.1"
},
"paymentMethod":{
"type":"GOOGLE_PAY",
"billingAddress":{
"street1":"4000 E 3rd Ave",
"city":"Foster City",
"state":"CA",
"countryCode":"US",
"zipCode":"94404",
"email":"mondee@test.com",
"phoneNumber":"1234567890"
},
"paymentNonce":"payment token from payload"
},
"cardStatement":{
"statementDescriptor":"test02",
"merchantReference":"3220a9c0",
"airlineName":"UA",
"originLocationCode":"SFO",
"destinationLocationCode":"ORD",
"departureDate":"12082020",
"flightSegments":[
{
"fromLocationCode":"SFO",
"toLocationCode":"ORD",
"departDate":"12082020",
"carrier":"UA",
"bookingClass":"G",
"stopOver":1
}
]
}
}";
| Param | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
| creditCard.expiryDate | string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
billingAddress.street1 |
string -Payment card billing street address as it appears on the credit card issuer’s records. |
billingAddress.city |
string -Payment card billing city. |
billingAddress. state</> |
string -State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
billingAddress.countryCode |
string -Payment card billing country. Use the two-character ISO Standard Country Codes. |
billingAddress.zipCode |
string-Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
billingAddress.email |
string -Customer's email address, including the full domain name. |
billingAddress.phoneNumber |
string -Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
flightSegments |
string Segment number information of the order to show on statement Descriptor Segment number information of the order to show on statement Descriptor |
flightSegments.fromLocationCode |
string the location code from where your start |
flightSegments.toLocationCode |
string the location code to where your destination |
flightSegments.carrier |
string airlines code we travel |
flightSegments.bookingClass |
string type of booking class which we book |
flightSegments.stopOver |
int no of stops inbetween |
Apple pay
var payObj = {
selector: "widgetDiv",
payElementId: "widget-pay-button",
finalAmount: "20.1",
countryCode: 'US',
currencyCode: 'USD',
};
payomo.init(function () {
payomo.widget.create(payObj, function (widgetInstance) {
console.log("widget created")
//bind click event
$("#" + payObj.payElementId).click(function () {
widgetInstance.submitPayment(function (payload) {
//apple pay
let cardNumber = payload.cardNumber;
let expiryDate = payload.expiryDate;
let cryptogram = payload.cryptogram;
let securityCode = payload.securityCode;
//pass above details in auth request and call payment auth method for Auth transaction
});
});
});
});
To finish your configuration, you will only need to complete the iCloud account and domain registration steps below.
iCloud account setup
When testing, you will need to be logged into an iCloud account that corresponds to your environment. Testing in sandbox requires you to be logged into an iTunes Connect sandbox tester account, which you can create with an Apple Developer account. Similarly, you will need to be logged into a production iCloud account when testing in production.
Domain registration
In order to test and accept Apple Pay on the web, you'll need to register any domains you plan to use with Apple. You should register your domain through the Apple Developer Portal
Setup and integration
Apple Pay is available in Safari on iOS version 10+ and macOS version 10.12+. If Apple Pay is not supported by the customer's browser, the options to select Apple Pay will not appear. For more information, see Apple's support articles on Apple Pay.
Call submitPayment method to get apple pay tokenized card details which includes
- card number
- expiry date
- cryptogram
- security code
Auth request for ApplePay
{
"transaction":{
"merchantReference":"test",
"amount":1.11,
"currency":"USD",
"transactionType":"AIR"
},
"customer":{
"customerId": {acccountId},
"sourceApp":"API",
"ipAddress":"127.0.0.1"
},
"paymentMethod":{
"type":"APPLE_PAY",
"billingAddress":{
"street1":"4000 E 3rd Ave",
"city":"Foster City",
"state":"CA",
"countryCode":"US",
"zipCode":"94404",
"email":"mondee@test.com",
"phoneNumber":"1234567890"
},
"tokenizedCard":{
"number":"cardNumber",
"expiryDate":"expiryDate",
"cryptogram":"cryptogram",
"securityCode":"securityCode"
}
},
"cardStatement":{
"statementDescriptor":"test02",
"merchantReference":"3220a9c0",
"airlineName":"UA",
"originLocationCode":"SFO",
"destinationLocationCode":"ORD",
"departureDate":"12082020",
"flightSegments":[
{
"fromLocationCode":"SFO",
"toLocationCode":"ORD",
"departDate":"12082020",
"carrier":"UA",
"bookingClass":"G",
"stopOver":1
}
]
}
}";
| Param | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
| creditCard.expiryDate | string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
billingAddress.street1 |
string -Payment card billing street address as it appears on the credit card issuer’s records. |
billingAddress.city |
string -Payment card billing city. |
billingAddress. state</> |
string -State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
billingAddress.countryCode |
string -Payment card billing country. Use the two-character ISO Standard Country Codes. |
billingAddress.zipCode |
string-Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
billingAddress.email |
string -Customer's email address, including the full domain name. |
billingAddress.phoneNumber |
string -Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
flightSegments |
string Segment number information of the order to show on statement Descriptor Segment number information of the order to show on statement Descriptor |
flightSegments.fromLocationCode |
string the location code from where your start |
flightSegments.toLocationCode |
string the location code to where your destination |
flightSegments.carrier |
string airlines code we travel |
flightSegments.bookingClass |
string type of booking class which we book |
flightSegments.stopOver |
int no of stops inbetween |
Paypal
var payObj = {
selector: "widgetDiv",
payElementId: "widget-pay-button",
finalAmount: "20.1",
countryCode: 'US',
currencyCode: 'USD'
};
payomo.init(function () {
payomo.widget.create(payObj, function (widgetInstance) {
console.log("widget created")
//bind click event
$("#" + payObj.payElementId).click(function () {
widgetInstance.submitPayment(function (payload) {
//paypal
var paymentToken = payload.paymentToken;
var paymentType = payload.selectedPaymentMethod;
//pass above details in auth request and call payment auth method for Auth transaction
});
});
});
});
Paypal Checkout:
Payomo widget provides Paypal Checkout option by providing Checkout button.Paypal production account is required to start with paypal checkout feature
Call submitPayment method to get paypal account related details which includes paypal payment token.
How it works
Flow of Paypal
Auth request for Paypal
{
"transaction":{
"merchantReference":"test",
"amount":1.11,
"currency":"USD",
"transactionType":"AIR"
},
"customer":{
"customerId": {acccountId},
"sourceApp":"API",
"ipAddress":"127.0.0.1"
},
"paymentMethod":{
"type":"PAYPAL",
"billingAddress":{
"street1":"4000 E 3rd Ave",
"city":"Foster City",
"state":"CA",
"countryCode":"US",
"zipCode":"94404",
"email":"mondee@test.com",
"phoneNumber":"1234567890"
},
"paymentNonce":"payment token from payload"
},
"cardStatement":{
"statementDescriptor":"test02",
"merchantReference":"3220a9c0",
"airlineName":"UA",
"originLocationCode":"SFO",
"destinationLocationCode":"ORD",
"departureDate":"12082020",
"flightSegments":[
{
"fromLocationCode":"SFO",
"toLocationCode":"ORD",
"departDate":"12082020",
"carrier":"UA",
"bookingClass":"G",
"stopOver":1
}
]
}
}";
| Param | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
creditCard.expiryDate |
string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
billingAddress.street1 |
string -Payment card billing street address as it appears on the credit card issuer’s records. |
billingAddress.city |
string -Payment card billing city. |
billingAddress. state</> |
string -State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
billingAddress.countryCode |
string -Payment card billing country. Use the two-character ISO Standard Country Codes. |
billingAddress.zipCode |
string-Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
billingAddress.email |
string -Customer's email address, including the full domain name. |
billingAddress.phoneNumber |
string -Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
flightSegments |
string Segment number information of the order to show on statement Descriptor Segment number information of the order to show on statement Descriptor |
flightSegments.fromLocationCode |
string the location code from where your start |
flightSegments.toLocationCode |
string the location code to where your destination |
flightSegments.carrier |
string airlines code we travel |
flightSegments.bookingClass |
string type of booking class which we book |
flightSegments.stopOver |
int no of stops inbetween |
Credit card
payomo.init(function () {
payomo.widget.create(payObj, function (widgetInstance) {
console.log("widget created")
//bind click event
$("#" + payObj.payElementId).click(function () {
widgetInstance.submitPayment(function (payload) {
//credit card
var cardNumber = payload.cardNumber;
var cardHolderName = payload.cardHolderName;
var expiryDate = payload.expiryDate;
var cvv = payload.cvv;
var cardType = payload.cardType;
var paymentType = payload.selectedPaymentMethod;
//pass above details in auth request and call payment auth method for Auth transaction
});
});
});
});
By default, cards will be enabled with
- Card holder name
- Card number
- Expiry date
- CVV
above fields are default ,when you configure the Widget .
Call submitPayment method to get a card related details which includes
- card number
- card holder name
- expiry date
- cvv
- card type
Auth request for cc
{
"transaction":{
"merchantReference":"test",
"amount":1.11,
"currency":"USD",
"transactionType":"AIR"
},
"customer":{
"customerId": {acccountId},
"sourceApp":"API",
"ipAddress":"127.0.0.1"
},
"creditCard":{
"cardHolderName":"cardHolderName",
"cardType":"cardType",
"expiryDate":"expiryDate",
"cardNumber":"cardNumber",
"cvv":"cvv",
"street1":"4000 E 3rd Ave",
"city":"Foster City",
"state":"CA",
"countryCode":"US",
"zipCode":"94404",
"email":"mondee@test.com",
"phoneNumber":"1234567890"
},
"cardStatement":{
"statementDescriptor":"test02",
"merchantReference":"3220a9c0",
"airlineName":"UA",
"originLocationCode":"SFO",
"destinationLocationCode":"ORD",
"departureDate":"12082020",
"flightSegments":[
{
"fromLocationCode":"SFO",
"toLocationCode":"ORD",
"departDate":"12082020",
"carrier":"UA",
"bookingClass":"G",
"stopOver":1
}
]
}
}";
Auth Request for CC
| Param | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
| creditCard.expiryDate | string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
billingAddress.street1 |
string -Payment card billing street address as it appears on the credit card issuer’s records. |
billingAddress.city |
string -Payment card billing city. |
billingAddress. state</> |
string -State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
billingAddress.countryCode |
string -Payment card billing country. Use the two-character ISO Standard Country Codes. |
billingAddress.zipCode |
string-Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
billingAddress.email |
string -Customer's email address, including the full domain name. |
billingAddress.phoneNumber |
string -Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
flightSegments |
string Segment number information of the order to show on statement Descriptor Segment number information of the order to show on statement Descriptor |
flightSegments.fromLocationCode |
string the location code from where your start |
flightSegments.toLocationCode |
string the location code to where your destination |
flightSegments.carrier |
string airlines code we travel |
flightSegments.bookingClass |
string type of booking class which we book |
flightSegments.stopOver |
int no of stops inbetween |
Auth
Payment Auth code
var payObj = {
selector: "widgetDiv",
payElementId: "widget-pay-button",
finalAmount: "20.1",
countryCode: 'US',
currencyCode: 'USD'
};
payomo.init(function () {
payomo.widget.create(payObj, function (widgetInstance) {
console.log("widget created")
//bind click event
$("#" + payObj.payElementId).click(function () {
widgetInstance.submitPayment(function (payload) {
var selectedPaymentType = payload.selectedPaymentMethod;
var authRequest = {};
if (selectedPaymentType == 'CREDIT_CARD') {
//prepare auth request for credit card
} else if (selectedPaymentType == 'PAYPAL') {
//prepare auth request for paypal
} else if (selectedPaymentType == 'GOOGLE_PAY') {
//prepare auth request for google pay
} else if (selectedPaymentType == 'APPLE_PAY') {
//prepare auth request for apple pay
}
widgetInstance.paymentAuth(authRequest, function (payload) {
//payload contains auth transaction ref number
console.log("payload=" + JSON.stringify(payload));
//payload contains below fields
var code = payload.code;
var messgae = payload.message;
var messageDescription = payload.messageDescription;
var merchantReference = payload.merchantReference;
//below param will be used in void or refund transactions
var transactionRefNumber = payload.pmTransactionReference;
var transactionType = payload.auth;
var amount = payload.amount;
var authorizationCode = payload.authorizationCode;
var transactionDate = payload.transactionDate;
var transactionTime = payload.transactionTime
});
});
});
});
});
curl --location --request POST "http://prod.payomo.com/api/v1/card/auth" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer hjgsfjndsolsdd623bhvnclasjfkwq92nsd" \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1.0,
\"currency\": \"USD\",
\"transactionType\": \"AIR\"
},
\"customer\": {
\"sourceApp\": \"API\"
},
\"creditCard\": {
\"cardHolderName\": \"Card holder name\",
\"cardType\": \"VI\",
\"expiryDate\": \"123\",
\"cardNumber\": \"4111111111111111\",
\"cvv\": \"123\",
\"street1\": \"Street address\",
\"city\": \"City name\",
\"state\": \"2-letter state code\",
\"countryCode\": \"2-letter country code\",
\"zipCode\": \"zipcode\",
\"email\": \"test@payomo.com\",
\"phoneNumber\": \"1234567890\"
},
\"cardStatement\": {
\"statementDescriptor\" : \"Descriptor\"
\"merchantReference\": \"test\",
\"airlineName\": \"2-letter airline name\",
\"originLocationCode\": \"SRC\",
\"destinationLocationCode\": \"DST\",
\"departureDate\": \"20200131\"
}
}"
Sale
Payment sale code
var payObj = {
selector: "widgetDiv",
payElementId: "widget-pay-button",
finalAmount: "20.1",
countryCode: 'US',
currencyCode: 'USD'
};
payomo.init(function () {
payomo.widget.create(payObj, function (widgetInstance) {
console.log("widget created")
//bind click event
$("#" + payObj.payElementId).click(function () {
widgetInstance.submitPayment(function (payload) {
var selectedPaymentType = payload.selectedPaymentMethod;
var authRequest = {};
if (selectedPaymentType == 'CREDIT_CARD') {
//prepare auth request for credit card
} else if (selectedPaymentType == 'PAYPAL') {
//prepare auth request for paypal
} else if (selectedPaymentType == 'GOOGLE_PAY') {
//prepare auth request for google pay
} else if (selectedPaymentType == 'APPLE_PAY') {
//prepare auth request for apple pay
}
widgetInstance.paymentSale(authRequest, function (payload) {
//payload contains auth transaction ref number
console.log("payload=" + JSON.stringify(payload));
//payload contains below fields
var code = payload.code;
var messgae = payload.message;
var messageDescription = payload.messageDescription;
var merchantReference = payload.merchantReference;
//below param will be used in void or refund transactions
var transactionRefNumber = payload.pmTransactionReference;
var transactionType = payload.auth;
var amount = payload.amount;
var authorizationCode = payload.authorizationCode;
var transactionDate = payload.transactionDate;
var transactionTime = payload.transactionTime
});
});
});
});
});
curl --location --request POST "https://prod.payomo.com/api/v1/card/sale" \
--header "Content-Type: application/json" \
--header "Authorization: " \
--data "{
\"transaction\": {
\"merchantReference\": \"test\",
\"amount\": 1.0,
\"currency\": \"USD\"
},
\"customer\": {
\"sourceApp\": \"API\"
},
\"creditCard\": {
\"cardHolderName\": \"Card holder name\",
\"cardType\": \"VI\",
\"expiryDate\": \"0919\",
\"cardNumber\": \"4111111111111111\",
\"cvv\": \"123\",
\"street1\": \"Street address\",
\"countryCode\" : \"2-letter country code\",
\"city\": \"City name\",
\"state\": \"2-letter state code\",
\"zipCode\": \"zipcode\",
\"email\": \"test@payomo.com\",
\"phoneNumber\": \"1234567890\"
},
\"cardStatement\": {
\"merchantReference\": \"test\",
\"airlineName\": \"2-letter airline code\",
\"originLocationCode\": \"SRC\",
\"destinationLocationCode\": \"DST\",
\"departureDate\": \"20191231\"
}
}"
Risk Check
Riskcheck request
{
"transaction":{
"merchantReference":"test",
"amount":1.11,
"currency":"USD",
"transactionType":"AIR"
},
"customer":{
"customerId": {acccountId},
"sourceApp":"API",
"ipAddress":"127.0.0.1"
},
"creditCard":{
"cardHolderName":"cardHolderName",
"cardType":"cardType",
"expiryDate":"expiryDate",
"cardNumber":"cardNumber",
"cvv":"cvv",
"street1":"4000 E 3rd Ave",
"city":"Foster City",
"state":"CA",
"countryCode":"US",
"zipCode":"94404",
"email":"mondee@test.com",
"phoneNumber":"1234567890"
},
"cardStatement":{
"statementDescriptor":"test02",
"merchantReference":"3220a9c0",
"airlineName":"UA",
"originLocationCode":"SFO",
"destinationLocationCode":"ORD",
"departureDate":"12082020",
"flightSegments":[
{
"fromLocationCode":"SFO",
"toLocationCode":"ORD",
"departDate":"12082020",
"carrier":"UA",
"bookingClass":"G",
"stopOver":1
}
]
}
}";
| Param | Description |
|---|---|
trasaction.merchantReference |
string ,Unique reference of the transaction. |
trasaction.amount |
string - Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters. |
trasaction.currency |
string -Currency used for the order. Use the three-character ISO Standard Currency Codes |
trasaction.trasactionType |
string -the type of an transaction |
customer.sourceApp |
string -Source of the application access point.Use "API" for API implementation |
customer.ipAddress |
string -Ip Address from which the order is getting created. |
creditCard |
string-The customer’s payment card number, also known as the Primary Account Number (PAN). |
creditCard.cardHolderName |
string-Name of the creditCard holder |
creditCard.cardType |
string -Three-digit value that indicates the card type. |
| creditCard.expiryDate | string -Two-digit month & Four-digit year in which the payment card expires. |
creditCard.cvv |
string -Card Verification Number. |
billingAddress.street1 |
string -Payment card billing street address as it appears on the credit card issuer’s records. |
billingAddress.city |
string -Payment card billing city. |
billingAddress. state</> |
string -State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada. |
billingAddress.countryCode |
string -Payment card billing country. Use the two-character ISO Standard Country Codes. |
billingAddress.zipCode |
string-Postal code for the billing address. The postal code must consist of 5 to 9 digits. |
billingAddress.email |
string -Customer's email address, including the full domain name. |
billingAddress.phoneNumber |
string -Customer’s phone number. |
cardStatement.statementDescriptor |
string -The statementDescriptor must consist less than 19 characters . |
cardStatement.airlineName |
string -Airline Code for statement Descriptor. Two Digit Airline code. |
cardStatement.originLocationCode |
string -Three digit Origin location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.destinationLocationCode |
string -Three digit Destination location information for statement Descriptor.Use the three-character ISO Standard Country Codes. |
cardStatement.departureDate |
string -Departure date of the order to show on statement Descriptor.Use the three-character ISO Standard Country Codes. |
flightSegments |
string Segment number information of the order to show on statement Descriptor Segment number information of the order to show on statement Descriptor |
flightSegments.fromLocationCode |
string the location code from where your start |
flightSegments.toLocationCode |
string the location code to where your destination |
flightSegments.carrier |
string airlines code we travel |
flightSegments.bookingClass |
string type of booking class which we book |
flightSegments.stopOver |
int no of stops inbetween |
Risk check code
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS =>"{\n \"transaction\":{\n \"merchantReference\":\"test\",\n \"amount\":1.11,\n \"currency\":\"USD\",\n \"transactionType\":\"AIR\"\n },\n \"customer\":{\n \"sourceApp\":\"API\",\n \"ipAddress\":\"127.0.0.1\"\n },\n \"creditCard\":{\n \"cardHolderName\":\"cardHolderName\",\n \"cardType\":\"cardType\",\n \"expiryDate\":\"expiryDate\",\n \"cardNumber\":\"cardNumber\",\n \"cvv\":\"cvv\",\n \"street1\":\"4000 E 3rd Ave\",\n \"city\":\"Foster City\",\n \"state\":\"CA\",\n \"countryCode\":\"US\",\n \"zipCode\":\"94404\",\n \"email\":\"mondee@test.com\",\n \"phoneNumber\":\"1234567890\"\n },\n \"cardStatement\":{\n \"statementDescriptor\":\"test02\",\n \"merchantReference\":\"3220a9c0\",\n \"airlineName\":\"UA\",\n \"originLocationCode\":\"SFO\",\n \"destinationLocationCode\":\"ORD\",\n \"departureDate\":\"12082020\",\n \"flightSegments\":[\n {\n \"fromLocationCode\":\"SFO\",\n \"toLocationCode\":\"ORD\",\n \"departDate\":\"12082020\",\n \"carrier\":\"UA\",\n \"bookingClass\":\"G\",\n \"stopOver\":1\n }\n ]\n }\n}",
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json"
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
**Risk check code**
> Riskcheck snippet in javascript
payomo.init(function () {
var request = {};
//prepare risk check request
payomo.riskcheck.submit(request, function (payload) {
//payload contains risk check transaction ref number
console.log("payload=" + JSON.stringify(payload));
//payload contains below fields
var score = payload.score;
var transactionRefNumber = payload.transactionRefNumber;
var status = payload.status;
});
});