menu

Payment API

What's on this page

General / Notifications

Notifications

A Notification is (similar to a Webhook) callback mechanism to inform you of events occurring in our system related to a transaction. This is accomplished by making an HTTP call to an endpoint in your system at the moment these events take place. Whereas a webhook does not contain any data next to the id (the referenceId), we will include information regarding the event and the notification itself.

Event Types

Notification Requests allow you to subscribe to certain events in order to receive a notification for those events. The following events are currently supported:

Event type Description
StatusChanged Results in a notification as the transaction status is changed. This would replace the standard Webhook when included.
Collected Results in a notification as the transaction is collected for balance processing in preparation for payout processing. This will only be triggered for collecting protocols
PaidOut Triggered as the transaction is processed and taken into account for payout to the merchant. This will only be triggered for collecting protocols.
AutoRefunded Results in a notification when the transaction is automatically refunded. This will only be triggered for collecting protocols.
AuthenticationStarted Results in a notification when the authentication process has started. If there is no authentication, no notification is sent.
AuthenticationCompleted Results in a notification when the authentication process has been completed, regardless of the authentication status.
MandateUpdated Results in a notification when a mandate is updated.
MandateUsed Results in a notification when a mandate is used to initiate a transaction.
TerminalMessageUpdate Results in notifications for intermediate messages (eg: Waiting for PIN) received from the terminal. In an attended terminal payment flow these messages can be handy when displayed to the cashier.

Duplicate event types are not allowed and each request must be accompanied by a URL to which we will send the notification.

It’s possible to include additional URL parameters for each notification to the notification URL, for example, an order reference. This would result in a notification URL like http://shop/notify?order=123456&foo=bar.

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "ideal",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "notificationRequests": [
          {
              "eventType": "StatusChanged",
              "notificationUrl": "https://notifiy.shop/1233455"
          }
      ]
}

Security

Due to security restrictions, we will only support https:// URLs. If you are technically not able to support this, please contact us.

For a more secure internet, you can look at services like Let's Encrypt that provide you certificates issued by a free and trusted Certificate Authority!

Notification Signing

In order to ensure that the Notification received originates from CCV, the request has a Signature header which is the result of signing the notification JSON request body. Verifying the signature is optional and is available as a security feature. The Public Key to perform this check can be obtained via this resource (which is also present as a full URL in the request JKWurl header):

  • Resource: /api/v1/notifications/jwk
  • Method: GET
  • Content-Type: application/json

For more information on JSON Web Keys, please visit JOSE4J on BitBucket.

The algorithm used is ECDSA_USING_P256_CURVE_AND_SHA256. The id of the key used to create the signature is present in the JWKkeyId header field of each notification request which indicates which cached key you should use to verify the signature. We strongly recommend caching the active keys.

Communication

Request

  • Method: POST
  • Content-Type: application/json
  • Parameters

The following parameters are common;

Name Description
id The unique reference of the transaction
eventType The type of event that triggered this notification
eventTimestamp The epoch timestamp that the event took place that triggered the notification
order The order this notification has in the sequence of requested notification types for the transaction
attempt The number of times this notification type was attempted for the transaction

Example

{
  "id" : "AP150513232281754007360.1",
  "eventType" : "Collected",
  "eventTimestamp" : 1420106400000,
  "order" : 2,
  "attempt" : 1
}

Certain events have additional parameters that may be included;

StatusChanged

Name Description
newStatus The new status of the transaction
failureCode If the status changed to failed the failure code will specify the reason.

Example

{
  "id" : "AP150513232281754007360.1",
  "eventType" : "StatusChanged",
  "eventTimestamp" : 1420106400000,
  "newStatus" : "FAILED",
  "failureCode" : "CANCELLED",
  "order" : 1,
  "attempt" : 1
}

PaidOut

Name Description
paidoutReference The reference used when performing the payout. This can be used to look up transactions related to that payout.
unstructuredMessage The unstructured message that will be visible on the customer’s bank statement.

Example

{
  "id" : "AP150513232281754007360.1",
  "eventType" : "PaidOut",
  "eventTimestamp" : 1420106400000,
  "paidoutReference" : "yourPayoutRef",
  "unstructuredMessage" : "someUnstructuredMessage",
  "order" : 3,
  "attempt" : 2
}

AuthenticationStarted

No additional parameters.

Example

{
  "id" : "AP150513232281754007360.1",
  "eventType" : "AuthenticationStarted",
  "eventTimestamp" : 1420106400000,
  "order" : 1,
  "attempt" : 1
}

AuthenticationCompleted

Name Description
status The status of the authentication. Values that are possible: SUCCESS, FAILED, UNKNOWN.

Example

{
  "id" : "AP150513232281754007360.1",
  "eventType" : "AuthenticationCompleted",
  "eventTimestamp" : 1420106400000,
  "status": "SUCCESS",
  "order" : 2,
  "attempt" : 1
}

MandateUpdated

Name Description
status The status of the mandate. Values that are possible: ACTIVE, INACTIVE.

Example

{
  "id" : "MAN210729090035746CB87E192.0",
  "eventType" : "MandateUpdated",
  "eventTimestamp" : 1420106400000,
  "status": "ACTIVE",
  "order" : 1,
  "attempt" : 1
}

MandateUsed

Name Description
childReferenceId The referenceId of the payment that used the mandate.

Example

{
    "id" : "MAN210729090035746CB87E192.0",
    "eventType" : "MandateUsed",
    "eventTimestamp" : 1420106400000,
    "childReferenceId": "P210729090128096CB87E190.1",
    "order" : 1,
    "attempt" : 3
}

TerminalMessageUpdate

Name Description
message The message to be displayed to the cashier
messageOrderNumber The order number of the message. The messages can be sent out of order. You should only display messages with a higher number than the currently displayed message

Example

{
  "id" : "AP150513232281754007360.1",
  "eventType" : "AuthenticationCompleted",
  "eventTimestamp" : 1420106400000,
  "message": "Payment in progress",
  "messageOrderNumber": 5,
  "order" : 2,
  "attempt" : 1
}

Response

We expect an HTTP 2XX Success code and the content will be ignored. If no 2XX code is returned, we will retry.

Best practices

It is strongly recommended to answer the notification with a 2xx HTTP status code as fast as possible. We recommend that you do not perform any heavy processing in your notification handler synchronously. Our system only sends a limited amount of parallel notifications to your system. If you block the notification handler by doing some processing, you might miss other webhooks. Instead, we suggest to use a queue system to process the notification asynchronously and to answer the notification immediately after receiving it.

Common mistakes

Replying with a redirect

CCV does not follow redirects. If you responds with a HTTP code that is less than 200 or greater than 299, CCV will retry the notification.

Using localhost in your notification

CCV does not send notifications to localhost. A notification url must be a public endpoint that CCV can access.

Not using a secure endpoint

CCV does not send notifications to insecure endpoints. See Security for more information