Use the Pay1st Console to generate the Webhooks and Callbacks for your integrations
Used in Gateway Integration
Overview
Webhooks and Callbacks are configured in order to redirect to the Partner’s servers once a payment’s status has been concluded. The following differences exist
- Webhooks are typically sent to a Partner's backend server
- Callbacks are typically used to redirect a Partner's customer in order to communicate payment status
List of Webhooks and Callbacks
The following table describes the Webhook and Callback configuration required for a Gateway Integration.
| Name | Type | Description |
|---|---|---|
| Webhook URL | String | This is used in order to send payment status updates to the Partner backend server. The payload sent to this URL is called Payment Webhook Events |
| Success Callback URL | String | After a successful payment, this URL will be used as the default URL when redirecting a customer |
| Failure Callback URL | String | After a failed payment, this URL will be used as the default URL when redirecting a customer |
| Pending Callback URL | String | When a payment is in a pending status, this URL will be used as the default URL when redirecting a customer |
| Cancel Callback URL | String | After a cancelled payment, this URL will be used as the default URL when redirecting a customer |
Payment Webhook Event List of Fields
The table below lists all the fields available in payment webhook events
| Name | Type | Mandatory | Description |
|---|---|---|---|
| partnerId | Number | Y | A numerical identifier of the Partner |
| partnerCode | String | Y | The unique code of the Partner. This should match the code configured in the Pay1st console |
| partnerReference | String | Y | The unique reference sent by the Partner in the Create Payment Request |
| reference | String | Y | The Pay1st reference of the Payment |
| orderAmount | Number | Y | The amount that was sent in the Create Payment Request |
| currencyCode | String | Y | The currency code that was sent in the Create Payment Request |
| countryCode | String | Y | The country code that was sent in the Create Payment Request |
| source | String | Y | The originating source of the Payment |
| platform | String | Y | The device platform used for the Payment. This will set to WEB |
| ipAddress | String | Y | The IP Address of the customer who made the Payment |
| createdDate | String | Y | The timestamp (in ISO-8601 format) that this Payment was created in the Pay1st Gateway |
| updatedDate | String | Y | The timestamp (in ISO-8601 format) of the last time that this Payment was updated by the Pay1st Gateway |
| status | String | Y | The current status of this Payment. Possible values are: ABANDONED, CANCELLED, CHARGEBACK, FAILED, NEW, PAY_OFFLINE, PENDING, PENDING_INVESTIGATION, READY, REFUND, SEND_BIRTHDAY, SEND_PHONE, SEND_PIN, SEND_OTP, SEND_VALIDATION_TOKEN, SUCCESSFUL, VALIDATED |
| message | String | Y | This contains the response message of the PSP used for the Payment |
| statusCode | Number | Y | The status code of the Payment |
| customerId | Number | Y | The customer identifier of this Payment |
| paymentMethod | String | Y | This is the payment method that has been used for the Payment |
| taxPercentage | Number | Y | The percentage of the Payment that represents tax |
| partnerWebhookUrl | String | Y | The partner webhook URL that was sent in the Create Payment Request |