Credit Transaction Result Callback and Webhook Listening
Shopping Credit Transaction Result and Webhook Integrations
Within the shopping credit integration, you should develop a new callback endpoint to listen to the credit results and if you are not receiving Webhook notifications, you should make improvements according to the instructions in Webhook Notifications. By listening to the calls/notifications from these endpoints, you can advance your payment transactions on your side.
When the transactions are completed on the financing institutions or banks side as a result of the shopping loan; The callbackUrl address you transmitted to the Craftgate system during the init request will be returned with the following parameters.
It is necessary to check that this return is made from the Craftgate system. For this, you need to refer to the Hash Value Generation and Control step in Security Recommendations.
Parameters Passed to Callback URL
The following parameters are passed as form variable using HTTP POST method. Since the merchant's callback address will be accessed from the user's browser, this address must be open to the internet and must be able to satisfy the application/x-www-form-urlencoded content-type.
The parameters in the request to callbackUrl by Craftgate after validation are as follows:
BNPL Payment ID. The ID value derived by the Craftgate API for the payment
Indicates the status of the BNPL payment. The payment status will be SUCCESS if successful, WAITING if pending, and FAILURE if unsuccessful
If there is an action that needs to be taken for the payment to continue, it expresses that value
Value of conversationId parameter sent in payment initiation request
If the bank or end user retriggers the 3DS validation step, the payment will be sent if it has already been validated. The Status field will receive the value FAILURE, while the callbackStatus will be sent with the value ALREADY_RETURNED. If this field receives the value ALREADY_RETURNED, you should check the status of the payment in your system and take no action if it is complete.
This is the field where the parameters used in hash calculation are sent sequentially. Parameters should be parsed according to the : character and the relevant parameter values should be added consecutively and included in the hash calculation.
The value of the Merchant Callback Key value is the value formed as a result of creating and combining the relevant values as described in the hashParams field and encrypting them with the Sha-256 Hex algorithm. Sample codes for the creation of the hash value are given below.
In order to make a successful integration, you need to develop the Webhook mechanism offered by the Craftgate system in addition to the Callback return. Credit processes are carried out differently in different banks, integrators and financing institutions. Since there are processes that need to be executed asynchronously, the Webhook mechanism should be followed and the BNPL_NOTIFICATION notification should be listened.
According to the HTTP POST operation to callbackUrl and the paymentStatus and additionalAction parameters in the Webhook notification, you need to develop the following constructs in your own system.
paymentStatus values:
| Value | Description |
|---|---|
SUCCESS | Reports successful completion of the credit process and payment. |
FAILURE | Indicates that the loan process was unsuccessful. |
WAITING | Indicates that the credit process is in progress. Action is taken according to additionalAction values. |
additionalAction values:
| Value | Description |
|---|---|
NONE | Used in the auto-approved loan application process. The loan has been extended to the customer and the merchant has received the payment. |
APPROVAL_REQUIRED | Used when not working with automatic approval. The credit is ready for use. After the checks by the merchant, the credit is disbursed by calling Shopping Credit Approval. |
WAIT_FOR_WEBHOOK | Used for banks that do not work with automatic approval and the application process is ongoing. The loan application is in the evaluation process. When the process is completed, the Craftgate system will be notified. Craftgate will also notify the merchant with Webhook Notification. By checking the additionalAction value in the Webhook message, the loan can be disbursed by making a loan approval service call. |
VERIFY_REQUIRED | The credit utilization status could not be queried or is unclear. It must be queried again by the merchant by making a Shopping Credit Verification service call. |