This page gives technical information on how to implement iGivePay in webshops. Payments are created through an API and the user should then be redirected according to result of the API call
¶ General description
The hosted payment integration is intended for integration between a vendor (typically a webshop) and iGivePay. It consists of the following steps:
- The vendor creates a new payment request from iGivePay.
- iGivePay responds with an identifier for the payment in iGivePay and a URL where the vendor can redirect the customer to continue the process of using their giftcards.
- The vendor redirects the user to the URI given in step 2, where they will perform payment or abort.
- The user is redirected back to a URI preconfigured by vendor
- The vendor can verify payment status by calling iGivePay API
- iGivePay API returns details about the processed payment (verified deducted amount, card information etc). See API specifications.
¶ Implementation information
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/
¶ Changelog
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
2022-10-10: Implemented:
- Redirect on payment completion or abortion
- Webhook on payment performed
2022-09-15: Initial API implementation is published
¶ Known limitations
The API currently doesn't perform redirects or calls webhooks on payment fullfilment, this will be implemented soon.The API will not actually deduct money from gift cards, although the payment status endpoint will say that the card has been deducted. This will be implemented as soon as possible.- Test version APIs might be unreliable at times during the day due to a servicing windows in test environment of a required third party system (CAS). This will likely not be fixed. Instability usually observed around 23:00-02:00 CEST.
Client credentials are currently set to a static vendor, so all payments are technically for a single vendorThe UI is still work in progress
¶ Authentication
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
¶ API calls
There are two API endpoints provided:
- Create a new Payment
- Verify Payment result
API definitions are available on API docs.
¶ Notes on payments
- The URL returned in payment creation contains an authentication token.
This token is time limited (current limit 60 minutes). This token restricts the user to allow only accessing the current Payment ID, so even if they were to guess or know any other payment IDs they would not be able to access them. - If the user completes or aborts the payment the payment will be marked as Completed or Aborted, and the URL for the payment will not remain accessible for the user.
This means that if the user decides to pay with iGivePay in two separate steps (one and one card), the integrator will have to create two separate payments as the first payment is inaccessible after status is marked as Completed/Aborted.
¶ Webhooks
Webhooks are an alternative way of notifying the integrator that something has happened with the payment. iGivePay currently supports the following events:
- Payment performed
Triggered once payment is confirmed
¶ Payment performed
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
}
}
¶ Gift cards
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.