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