Get notified of a charge status change
Receive notifications of transaction status changes as your user progresses through the payment flow.
Coda will issue server-to-server notifications to keep you updated on the payment status. Depending on the transaction's progress, you may receive one or several notifications, each reflecting the current state of the payment.
Pre-requisite
The transaction completion notification URL is configured
Payment notifications
Notification to be received for Authorize, Captured, Succeed, Failed payment statuses
Current Environment Availability
Sandbox
Yes
Production
Yes
Notification Parameters
id
String
identifier of notification event
data
JSON Object
data that contain charge information Object
Headers
x-signature
The signature created by requestTime and requestBody, encrypted by using HMAC512 algorithm.
x-request-time
The epoch timestamp when the request was created.
Steps:
Append the values listed below as a string as follows: "{requestTime}.{requestBody}" Example:
Calculate the HMAC-SHA512 hash of the string using your signing secret as the key. The signing secret is a pre-shared key configured for your webhook endpoint. The HMAC-SHA512 algorithm will return a byte array value.
Example:
Convert the byte array value to a hexadecimal string. The result will be like:
"a0c2d905877e9282a3954743f918f98f991c144020c535458c84767b6e146cf8cad4433accc2047258f6d5c4be07264596cfc58cfeea9e8551090f26e828e6bd"
Verifying the Signature
Extract the X-Request-Time and X-Signature headers from the webhook request
Get the raw request body as a string (before any parsing)
Generate the expected signature following Steps 1-3 above
Compare the generated signature with the X-Signature header value using a constant-time comparison
Verify that the X-Request-Time is within an acceptable time window (e.g., within last 5 minutes) to prevent replay attacks
data
Data contains an object similar to the charge object which you get from Get Charge Data endpoint response.
Below are the fields you need to focus on:
id
String
Identifier of charge
created_at
Instant
Timestamp of when the charge was created
error_description
String
The error code description of a failed charge. See full list of possible error code description here.
partner_reference
String
ID provided by the partner for the payment
Capture Approval Notification
Current Environment Availability
Sandbox
Yes
Production
Yes
Coda will issue a server-to-server REST connection to ask you what action coda should perform after successful payment authorization.
Capture Parameters
The contract of the Capture Request is similar to Payment notifications, except it is not wrapped to a data object.
Below are the fields you need to focus on:
id
String
Identifier of charge
created_at
Instant
Timestamp of when the charge was created
status_code
String
Current State of the payment. See the full list of possible statuses here.
You should expect waiting_capture_approval status.
partner_reference
String
ID provided by the partner for the payment
How to activate
You should pass the pre_capture_ack_url parameter to the Submit Charge request. Otherwise, all authorized charges will be automatically captured.
Once the issuing bank has authorized the payment, if we received pre_capture_ack_url, then we will send the capture request notification as REST Request.
The request from coda should contain a charge object with status_code: waiting_capture_approval.
This will indicate that the authorization was completed and Coda is waiting for your acknowledgement.
What you should response
You can optionally choose to authorize or decline a transaction after the user has confirmed the payment and issuing bank has authorized it.
If you want to have the option to decide if you want to
(a) proceed with capture or
(b) to cancel an authorized charge
You will need to reply to the notification call to tell us whether the capture for that charge can proceed. The response should be as follows (see samples here):
charge_id
String
Unique identifier for the charge
perform_action
String
Indicates whether the capture request is approved or declined by sending confirm_capture or decline_capture
Retry policy
Current Environment Availability
Sandbox
Coming soon
Production
Coming soon
Please note that, if we don’t receive a response to the capture notification, we will resend the capture request 3 times, a few minutes apart. If the retries don’t work, we will assume that the merchant has declined the charge and we will not proceed with the capture of the funds.
For all notifications, If our POST request does not receive a 2XX response, we will employ an exponential backoff strategy and retry the request up to three times.
Retry Schedule After Initial Failure:
First Retry: 1 Minute
Second Retry: 5 Minutes
Third Retry: 30 Minutes
After 3 failed retries, we will not process the event further. For the capture request notification, after 3 failed retries, we will not process the event further and we will assume that the capture request has been declined. This means that the charge will be canceled and we will issue a status change notification with payment status as canceled.
Last updated
Was this helpful?