Integration Overview
Overview
ZeroGateway.js is a JavaScript framework that allows merchants to collect sensitive payment information from their customers without exposing their website to the sensitive information. This can be done while allowing merchants to retain full control over the look and feel of their checkout experience. This is a data collection and tokenization system, not a full payments API, so you can use this in conjunction with an existing transaction API (see API description on this documentation) to submit transactions or use other gateway services that utilize payment information.
Authentication
To load the script that embeds the tokenization form in your page, you have to be authenticated with a key. Such key can be found in your Merchant Settings page under the Security Keys settings page. Select the key that has Tokenization as source. This tokenization key can only be used with ZeroGateway.js and will not work with any other APIs. Similarly, any API keys already created will not work with ZeroGateway.js. This key will be visible to customers in your website's source code, so please make sure you only use the tokenization key here.
Tokenization Form
Step 1: Create a basic web page.
Create a file index.html like this:
<html lang="en">
<head>
<meta charset="utf-8">
<title>Demo</title>
<base href="/">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body></body>
</html>
Step 2: Initialize form.
Proceed to add the form where the sensitive payment info will be collected.
<form>
<table>
<tr>
<td>Card Number</td>
<td id="demoCcnumber"></td>
</tr>
<tr>
<td>Card Expiration</td>
<td id="demoCcexp"></td>
</tr>
<tr>
<td>CVV Code</td>
<td id="demoCvv"></td>
</tr>
</table>
<button id="customPayButton">Confirm Payment</button>
</form>
These IDs are expected to be used in place of standard form inputs for credit card payments:
ccnumber- (Credit card number)ccexp- (Credit card expiration date)cvv- (CVV Code)
Step 3: Initialize the JS object.
Add in the head of your payment form page the following script:
<script src="https://gateway.paywithzero.net/v1/gateway/ZeroGateway.js" data-tokenization-key="your-token-key"></script>
your-token-key your-token-key, is generated for your merchant, and it can be obtained in the Merchant Settings, under Security Keys. Please select the one with Tokenization source.
3455zJms-7qA2K2-VdVrSu-Rv7WpvPuG7s8 Tokens are not reusable
Step 4: JS object settings.
The DOMContentLoaded event is triggered when the HTML document has been fully loaded and parsed. Then you can customize the experience more to your liking. This is a basic example:
<script>
document.addEventListener('DOMContentLoaded', function () {
CollectJS.configure({
'paymentSelector': '#customPayButton',
"fields": {
"ccnumber": {
"selector": "#demoCcnumber",
"title": "Card Number",
"placeholder": "0000 0000 0000 0000"
},
"ccexp": {
"selector": "#demoCcexp",
"title": "Card Expiration",
"placeholder": "00 / 00"
},
"cvv": {
"display": "show",
"selector": "#demoCvv",
"title": "CVV Code",
"placeholder": "***"
},
},
"price": "1.00",
"currency": "USD",
"country": "US",
"variant": "inline",
"callback": function (response) {
// create a new element to render the response token
var input = document.createElement("input");
input.name = "payment_token";
input.value = response.token;
var form = document.getElementsByTagName("form")[0];
form.appendChild(input);
}
});
});
</script>
The response.token obtained in this step will be your payment token. This payment token represents the card information, and it can (and should) be used to pay calling the API.
Payment tokens are not reusable. Every time a token is used, it will be disposed and a new one must be generated. Even in the event of declined payment.
To be seen at its full potential you can add some configurations to the configure() method:
"googleFont": "Montserrat:400",
"customCss" : {
"color": "#0000FF",
"background-color": "#D0D0FF"
},
"invalidCss": {
"color": "white",
"background-color": "red"
},
"validCss": {
"color": "black",
"background-color": "#D0FFD0"
},
"placeholderCss": {
"color": "green",
"background-color": "#808080"
},
"focusCss": {
"color": "yellow",
"background-color": "#202020"
},
'validationCallback' : function(field, status, message) {
if (status) {
var message = field + " is now OK: " + message;
} else {
var message = field + " is now Invalid: " + message;
}
console.log(message);
},
"fieldsAvailableCallback" : function () {
console.log("ZeroGateway.js loaded the fields onto the form");
}
API Integration
The Strictly public API contains a set of endpoints that can be hit with proper authentication.
Step 1: Obtain your security credentials.
Go to the Merchant Settings and from there select Security Keys. On that page you can create and see access keys specifying the user that is being authorized to use the API (These keys are denoted as source: API)
Step 2: Call the API.
For each subsequent API call you will need the security key, the username and the password for the user associated with the key. It is very important to note that your call to the API must happen from a server side application, since you will be sending sensitive information. This sensitive information should be sent in the headers:
headers: {
authorization: basicAuth,
key-hash: your-security-key,
}
The Basic Auth will be conformed using the username and password.
Authorization: Basic {base64_encode(username:password)}
A full API Reference can be found here, but as a general rule you can send a request to the API as follows: cURL
Payment with card
curl --location
--request POST 'https://api.paywithzero.net/v1/public/payment/charge' \
--header 'Content-Type: application/json' \
--header 'key-hash: YJU56X2NKLVBFLHGEA7J' \
--header 'Authorization: Basic amxib3JyZXJvQGdtYWlsLmNvbToxcWF6eHN3Mg==' \
--data-raw '{
"amount": 5,
"contact": {
"email": "[email protected]",
"phone": "5555555555"
},
"billingAddress": {
"address": "demo",
"city": "demo",
"country": "US",
"state": "Alaska",
"zipCode": "10400"
},
"shippingAddress": {},
"order": {
"amount": 2,
"shipping": 0 ,
"tax": 0,
"poNumber": "65614",
"discount": 0
},
"capture": true,
"card": {
"name": "Demo Card",
"paymentToken": "00000000-000000-000000-000000000000",
"number": "411111******1111"
}
}'
paymentToken: This will be generated by ZeroGateway.js and is usable only once.
Payment with customer
curl --location
--request POST 'https://api.paywithzero.net/v1/public/payment/charge' \
--header 'Content-Type: application/json' \
--header 'key-hash: YJU56X2NKLVBFLHGEA7J' \
--header 'Authorization: Basic amxib3JyZXJvQGdtYWlsLmNvbToxcWF6eHN3Mg==' \
--data-raw '{
"amount": 5,
"contact": {
"email": "[email protected]",
"phone": "5555555555"
},
"billingAddress": {
"address": "demo",
"city": "demo",
"country": "US",
"state": "Alaska",
"zipCode": "10400"
},
"shippingAddress": {},
"order": {
"amount": 2,
"shipping": 0 ,
"tax": 0,
"poNumber": "65614",
"discount": 0
},
"capture": true,
"card": {
"vaultId": "6037d45411ccca001c4e4287",
}
}'
Response Sample
{
"data": {
"id": "62264b0b15b2da2e2aa5c0d0",
"object": "charge",
"type": "sale",
"amount": 5,
"baseAmount": 5,
"surcharge": 0,
"captured": true,
"transactionId": "7040635314",
"error": false,
"createdAt": "2022-03-07T18:12:27.512Z",
"transactionAt": "2022-03-07T18:12:27.512Z",
"settled": false,
"userAgent": "curl/7.68.0",
"device": "api",
"paymentId": "62264b5f15b2da2e2aa5c0d2",
"createdBy": "[email protected]",
"updatedBy": "[email protected]" ,
}
}
Response Sample error
{
"statusCode": 400,
"timestamp": "2022-04-11T22:54:13.822Z",
"path": "/v1/public/payment/charge",
"response": {
"code": "300",
"text": "Transaction was rejected by gateway."
},
"message": "Http Exception"
}
| Code | Messages |
|---|---|
| 200 | Transaction was declined by processor. |
| 201 | Do not honor. |
| 202 | Insufficient funds. |
| 203 | Over limit. |
| 204 | Transaction not allowed. |
| 220 | Incorrect payment information. |
| 221 | No such card issuer. |
| 222 | No card number on file with issuer. |
| 223 | Expired card. |
| 224 | Invalid expiration date. |
| 225 | Invalid card security code. |
| 226 | Invalid PIN. |
| 240 | Call issuer for further information. |
| 250 | Pick up card. |
| 251 | Lost card. |
| 252 | Stolen card. |
| 253 | Fraudulent card. |
| 260 | Declined with further instructions available. (See response text) |
| 261 | Declined-Stop all recurring payments. |
| 262 | Declined-Stop this recurring program. |
| 263 | Declined-Update cardholder data available. |
| 264 | Declined-Retry in a few days. |
| 300 | Transaction was rejected by gateway. |
| 400 | Transaction error returned by processor. |
| 410 | Invalid merchant configuration. |
| 411 | Merchant account is inactive. |
| 420 | Communication error. |
| 421 | Communication error with issuer. |
| 430 | Duplicate transaction at processor. |
| 440 | Processor format error. |
| 441 | Invalid transaction information. |
| 460 | Processor feature not available. |
| 461 | Unsupported card type. |
| 900 | Bad request, form validation error (See response message). |
| 901 | Required Card Information. |
| 902 | VaultId or PaymentToken is required. |
| 903 | Merchant with id: ClientId not found. |
| 904 | The apply discount option is disabled for this merchant. |
| 905 | Card number is required. |
| 906 | Vault with id: VaultId not found. |
| 907 | It seems to be a mismatch in the client's credit rate configured in your merchant. |
| 908 | We do not accept Debit Cards Payments. |
| 909 | Unsupported card type. |
| 999 | Communication error. |
Validation
| Field | Validation | Example |
|---|---|---|
| card.number | RegExp: /\d{6}[*\.]+\d{4}/g Required is vaultId is empty |
411111***1111 |
Test Values
Card Numbers
When your account in in test mode (sandbox account) we have designated the following cards to be used for testing:
| Brand | Number | Card Type |
|---|---|---|
| Visa | 4111111111111111 4000000000000002 |
Credit Credit |
| MasterCard | 5115055555555551 5121212121212124 |
Debit Credit |
| Discover | 6011973700000005 6011402344444445 |
Debit Credit |
| American Express | 370000000000002 | Credit |
Card Expiration: 10/25
Triggering Errors:
- To cause a declined message, pass an amount less than 1.00.
- To trigger a fatal error message, pass an invalid card number.
Payment Token
| Payment Token Value | Test Data |
|---|---|
| 00000000-000000-000000-000000000000 | Card: 4111111111111111, Expiration: October 2025, CVV: 999 |
This will be generated by ZeroGateway.js and is usable only once.
Webhooks
Webhooks are a way for software applications to send automated messages or information to other applications. Strictly use webhooks to communicate to customers integrations about specific events that occurred.
Available events are:
- Sale
- Auth
- Capture
- Void
- Refund
- Invoice Paid
- Payment Link Paid
- Subscription Paid
Strictly Webhooks are sent using POST method and merchant integration is responsible to return a 200 status code for success calls and accessible from public networks.
Strictly implements a retry mechanism for response codes different than 200. Such mechanism will attempt to call 2 more times the specified url in case of failure.
The authentication is optional, but if security is needed, the system will use Basic Authentication (Username and Password entered under Merchant Settings → Webhooks → Authentication section).
Sale event can be made by two different payment methods: card payment or Ach payment.
Card Payment Sample
{
"date": ISODate("2022-11-14T11:42:51.584-05:00"),
"attempted": 1,
"failed": false,
"failureMessage": null,
"sendAt": ISODate("2022-11-14T11:42:52.855-05:00"),
"server": {
"path": "https://webhook.site/09ec9f61-db3d-457a-860c-b49fb8b3af68",
"username": "test",
"password": "testDemo3232"
},
"data": {
"paymentId": "636e7b8953e9d437d0d2ee8e",
"order": {
"shipping": 0,
"federalTaxes": 0,
"amount": 100,
"tax": 0,
"discount": 0,
"customValues": [
{
"value": "er4",
"key": "Number",
"label": "Number"
}
],
"products": []
},
"currency": "USD",
"card": {
"cardType": "amex",
"last4": "0005",
"exp": "0724",
"type": "credit"
},
"paid": true,
"amount": 100,
"surcharge": 4,
"percent": 3.5,
"status": "sale",
"paidAmount": 100,
"paidAmountSurcharge": 4,
"amountRefunded": 0,
"surchargeRefunded": 0,
"error": false,
"transactionErrorMsg": null,
"statusList": ["sale"],
"sendReceipt": true,
"settled": false,
"transactionId": "7782652079"
"paymentType": "credit",
},
"action": "sale"
}
ACH Payment Sample
{
"date": ISODate("2022-11-14T11:45:13.735-05:00"),
"attempted": 1,
"failed": false,
"failureMessage": null,
"sendAt": ISODate("2022-11-14T11:45:14.905-05:00"),
"server": {
"path": "https://webhook.site/09ec9f61-db3d-457a-860c-b49fb8b3af68",
"username": "test",
"password": "test323235321"
},
"data": {
"paymentId": "63727098ddfbc648aff9082f",
"order": {
"shipping": 0,
"federalTaxes": 0,
"amount": 8,
"tax": 0,
"discount": 0,
"poNumber": "65614",
"products": [],
"customValues": []
},
"currency": "USD",
"paid": true,
"amount": 8,
"surcharge": 0,
"percent": 0,
"status": "sale",
"paidAmount": 8,
"paidAmountSurcharge": 0,
"amountRefunded": 0,
"surchargeRefunded": 0,
"error": false,
"transactionErrorMsg": null,
"statusList": ["sale"],
"sendReceipt": true,
"settled": false,
"transactionId": "1000000070",
"paymentType": "ach",
"achData": {
"accountType": "Savings",
"last4": "9999"
}
},
"action": "sale"
}
Sample Application
For your convenience we have created a few sample applications for client side and one server side application here.