Gateway API is a direct server-to-server connection between the merchant and Freedom Pay: the merchant collects card data on its side and sends it to the API, without the Freedom Pay payment page.
Gateway API has two independent APIs: Sync API and Async API.
Connection requires a PCI DSS certificate.
Sync API and Async API#
| Sync API (API v3) | Async API (API v5) |
|---|
| URL | {domain}/g2g/<method>, a separate URL per operation | {domain}/v5/g2g/create, /read, /edit; the operation is set by the X-Action header |
| Result | in the response to the request | the request is accepted with status process; the result is available via the status request |
| Request and response | form data, JSON or XML; the response is XML | JSON |
| Signature | MD5 pg_sig | JWS X-JWS-Signature (HS256) |
| Operations | payments by card and wallet token, 3DS, clearing, cancel, refund, recurrent payments, payouts, transfers, card storage | payments by card, saved card, wallet token and recurrent profile; 3DS; clearing, reverse, refund |
| Callbacks | for payouts and payment pages: see «Callbacks» in Sync API Overview | no: get the result with the status request |
Test mode#
Sync API: to make a test payment, pass pg_testing_mode = 1 in the request.
Test cards work only in test mode and do not work for Apple Pay and Google Pay.
The results below were obtained with cardholder name IVAN IVANOV, CVC 123 and expiry date 12/30.
Which card to use#
| What you test | Card number | 3DS |
|---|
| Payment, clearing and refund | 4716047261941981 | No |
| Payment, clearing, reverse (cancel) and refund | 6224466455690681278 | No |
| Payment and reverse (cancel) | 4939770956154989 | No |
| Payment with 3DS and clearing | 4916307416334310 | Yes |
| Payment with 3DS and reverse (cancel) | 5367654276102126 | Yes |
| Declined payment: insufficient funds | 4400444400004443 | No |
| Declined payment: limit exceeded | 4400444400004442 | No |
| Declined payment: payment system error | 4400444400004441 | No |
| Declined payment: system error | 4400444400004445 | No |
| Declined payment: 3DS authentication failed | 4400444400004447 | Yes |
| Payout: success | 4400444444444440 | — |
| Payout: declined | 4400444444444441 | — |
Payout: stays in status process | 4400444444444444 | — |
The full lists are below. — the operation succeeds, — the operation is declined.Payment cards: successful payment#
| Card number | Brand | 3DS | Clearing | Reverse (cancel) | Refund |
|---|
| 4400444400004440 | Visa | | | | |
| 4400444400004444 | Visa | | | | |
| 4458444400004448 | Visa | | | | |
| 4716047261941981 | Visa | | | | |
| 4916307416334310 | Visa | | | | |
| 5367654276102126 | Mastercard | | | | |
| 4939770956154989 | Visa | | | | |
| 4799150896081734 | Visa | | | | |
| 5218487962459752 | Mastercard | | | | |
| 4446763125813623 | Visa | | | | |
| 5200190005138652 | Mastercard | | | | |
| 5269737320050521 | Mastercard | | | | |
| 5377193762823307 | Mastercard | | | | |
| 5200190059838710 | Mastercard | | | | |
| 5163103002982563 | Mastercard | | | | |
| 5486742060635314 | Mastercard | | | | |
| 5200190011811433 | Mastercard | | | | |
| 4090700100360047 | Visa | | | | |
| 5167400000496745 | Mastercard | | | | |
| 4256691944867646 | Visa | | | | |
| 4284624140544525 | Visa | | | | |
| 4985170000702810 | Visa | | | | |
| 4356292313685179 | Visa | | | | |
| 6200000000000013 | UnionPay | | | | |
| 62000000000000018 | UnionPay | | | | |
| 620000000000000013 | UnionPay | | | | |
| 6200000000000000018 | UnionPay | | | | |
| 6200000011111114 | UnionPay | | | | |
| 62000000111111118 | UnionPay | | | | |
| 620000001111111111 | UnionPay | | | | |
| 6200000011111111115 | UnionPay | | | | |
| 6224466455690681278 | UnionPay | | | | |
| 62528733472390953 | UnionPay | | | | |
| 623275279933273424 | UnionPay | | | | |
| 4111111111111111 | Visa | | | | |
| 5555555555555599 | Mastercard | | | | |
| 4671593866478252 | Visa | | | | |
For cards with 3DS the payment returns pg_3ds = 1: complete the 3DS step (/g2g/paymentAcs) to get the final result.
Save card saves a card from this table.
A card with 3DS is saved after Save card: complete 3DS.Payment cards: declined payment#
| Card number | Brand | 3DS | Result |
|---|
| 4400444400004441 | Visa | | Payment system error |
| 4400444400004442 | Visa | | Limit exceeded |
| 4400444400004443 | Visa | | Insufficient funds |
| 4400444400004445 | Visa | | System error |
| 4400444400004446 | Visa | | Payment system error |
| 4400444400004447 | Visa | | 3DS authentication failed |
| 5335215945367703 | Mastercard | | Payment system error |
| 4916109830832246 | Visa | | Limit exceeded |
| 5548398681700148 | Mastercard | | Insufficient funds |
| 5475102935853613 | Mastercard | | System error |
| 5484458131482832 | Mastercard | | 3DS session error |
| 6200000022222215 | UnionPay | | Payment system error |
| 62000000222222226 | UnionPay | | Payment system error |
| 620000002222222227 | UnionPay | | Payment system error |
| 6200000022222222220 | UnionPay | | Payment system error |
| 6200000033333316 | UnionPay | | Limit exceeded |
| 62000000333333334 | UnionPay | | Limit exceeded |
| 620000003333333333 | UnionPay | | Limit exceeded |
| 6200000033333333335 | UnionPay | | Limit exceeded |
| 6200000044444417 | UnionPay | | Insufficient funds |
| 62000000444444442 | UnionPay | | Insufficient funds |
| 620000004444444449 | UnionPay | | Insufficient funds |
| 6200000044444444440 | UnionPay | | Insufficient funds |
| 4444444444446666 | Visa | | Payment system error |
| 4563960122001999 | Visa | | Limit exceeded |
| 5555555555555557 | Mastercard | | System error |
| 4444444444444422 | Visa | | System error |
| 4444444411111111 | Visa | | System error |
| 4444444499999999 | Visa | | System error |
Save card does not save a card from this table: the response contains pg_error_code.Payout cards#
| Card number | Result |
|---|
| 4400444444444440 | Success |
| 4671593866478252 | Success |
| 4860515915886350 | Success |
| 4860371715886350 | Success |
| 4860169115886354 | Success |
| 4860502915886358 | Success |
| 4860041015886356 | Success |
| 4860050615886351 | Success |
| 4860518515886358 | Success |
| 4860967315886359 | Success |
| 4860862015886355 | Success |
| 6204500338419360939 | Success |
| 62861819783765929 | Success |
| 629656013969216940 | Success |
| 4400444400004440 | Success |
| 4458444400004448 | Success |
| 4400444444444441 | Declined |
| 4400444444444442 | Declined |
| 4400444444444443 | Declined |
| 5325349472901311 | Declined |
| 4556046085041740 | Declined |
| 5543974702876045 | Declined |
| 4400444444444444 | Stays in status process |
| 4400444444444445 | Stays in status process |
| 5507841999732294 | Stays in status process |
| 4532676596620704 | Stays in status process |
Error codes#
The error format of each API is described in its Overview.
Support#
If you find an inaccuracy in the documentation or need help with the integration, write to support@freedompay.kz. For connection and merchant settings, contact your account manager.