The page describes handling payments for integrations with Point of Sale systems.
The solutions described on this page are intended for integratings with Point of Sale (POS) systems. iGivePay supports two different modes:
See below for notes on API-only payment responses.
See below for notes on WebUI-payments.
API endpoint (devTEST): https://payapi.test.igive.xyz/
API documentation: https://payapi.test.igive.xyz/docs-v1/
API endpoint (production): https://pay.api.igive.no/
2023-11-22: Documentation of new mode: Api-Only Payments. Now available in test environment. In production late December or January.
2023-10-30: Slight modification to URL for creating cards in test environment. See section below.
2023-04-17: Added production endpoint and removed warning about possibility of breaking API changes
2023-02-19: Implementation is near feature complete and is considered in beta status
2022-10-10: Implemented:
2022-09-15: Initial API implementation is published
Any API calls requires the caller to provide a Client ID and Client Secret provided by iGive.
Contact iGive to get authentication details and gift cards to use in test environment.
When Api-Key and Api-Secret has been provided, please set the x-client-id and x-client-secret header on your requests to provide the values when calling the APIs
There are two API endpoints provided:
API definitions are available on API docs.
In order to use API-payments, please remember to set accessMode: “api” when creating the payment. Otherwise PerformPayment-endpoint will respond with error code. Also note that currently the Create Payment endpoint will respond with a WebUI-link in addition to the payment ID as documented on the create payment endpoint. Feel free to ignore this WebUI-link.
The perform payment endpoint will respond similar to the verify endpoint if payment succeeded. If payment fails with status code 400 (Bad Request) you can use the table below to interpret error codes:
| Error code: | Meaning: |
| 100 | Your client is not configured to accept cards from the vendor of the provided gift card |
| 101 | Gift card is expired |
| 102 | Gift card has no balance |
| 105 | Your client is not configured to accept cards from the vendor of the provided gift card |
| 106 | Gift card has no balance |
| 109 | Card not found |
| 250 | Balance not sufficient for fulfilling request |
| 251 | Payment state is not valid (payment is aborted/completed etc.) |
| 252 | Error fetching DCVV card info (similar to CVV) |
| 253 | Error in communication with payment processor |
| 254 | Generic payment provider error |
| 257 | Payment is not created with API-access flag |
| 258 | Payment metadata mismatch against the API-callers authentication credentials |
| 259 | Payment ID is invalid |
| 260 | Payment was not created by same client id |
| 400 | Expected length of card number is 19 |
| 401 | Card number should only contain digits and should validate as a positive number |
| 402 | Card number is not valid |
| 950 | Missing data in call |
Please note, this table is still work in progress and might change before production release. Any changes will be announced in changelog section further up this page.
Error response on BadRequest will be formed like this:
{ "error": 105 }
Webhooks are an alternative way of notifying the integrator that something has happened with the payment. iGivePay currently supports the following events:
If webhook is configured when creating the payment, the following webhook will be pushed when the API has processed the payment:
Please note that card numbers will be masked and only contain the last 5 digits.
{
"paymentId": string,
"paidAmount": number,
"paymentTotal": number,
"reference": string,
"cards": Array:
{
cardNumber: string,
deductedAmount: number
}
}
You can create gift cards in our test environment by going to the following URL: https://data.test.igive.xyz/card-gen.
Just enter a valid API Client ID that you have received from iGive, and you should be able to create giftcards with amounts ranging from 0 - 10.000 NOK. These cards can then be used to perform payments in the test environment.