Single payment status updates
The time it takes a bank to process a PIR can vary and may not be instant. Because of this, Vyne provides updates when the status of a payment changes.
There are different methods to obtain the status of the payment.
| Method | Description | Use case |
|---|---|---|
| Callback URL payload | A payload appended to the callback URL - the URL a consumer is redirected to after they have completed a payment. | Presenting an immediate confirmation to the consumer at the end of the payment flow. The payload allows the merchant to display a receipt (for example, if payment is cancelled by the consumer). |
| Webhook notifications | Webhook notification of a status change on the payment. | Be notified as soon as the payment status changes. |
| Get payments | Get the status of the payment manually. | If a manual update is required on demand, merchants can get the status of the payment at any time. |
Using the callback URL payload
After the consumer authorises the payment at their bank, you should direct them to a confirmation page. For every PIR, you'll need to provide a callbackUrl parameter. Vyne redirects the consumer to the callbackUrl at the end of every payment flow, regardless of the payment's outcome.
In order to allow merchants to provide consumers with feedback reflecting the payment status, Vyne provides payment information in a payvyne_payment_payload parameter appended to the callbackUrl. payvyne_payment_payload includes paymentId and paymentStatus as claims in a Base64 encoded JSON Web Token, provided as:
https://merchant.site?payvyne_payment_payload=eyJraW...5MwvsUjZpqY7p_jZo (sample)
Header
{
"kid": "aeaf334e-9a54-41e8-961a-e3838081fd5c",
"alg": "RS256"
}
| Parameter | Description |
|---|---|
| kid | JWT key identifier. |
| alg | JWT signing algorithm. |
Payload
{
"jti": "46406996-1a33-4eef-a891-25077a576676",
"iss": "http://app.payvyne.com",
"sub": "payment_info",
"paymentStatus": "COMPLETED",
"paymentId": "787fd82e5578fc3b",
"iat": 1608226143,
"exp": 1608227943
}
| Parameter | Description |
|---|---|
| iss | The principal that issued the JWT |
| sub | Type of data |
| paymentStatus | The current status of the payment. For all possible statuses see here. |
| paymentId | 16 digit alphanumeric unique payment identifier. |
| iat | JWT issue time |
| exp | JWT expiry time |
JWT integrity
The integrity of the token can be verified by using either one of the industry standard libraries provided by JWT.io, corresponding to your platform's programming language. Verification can be done by using one of the public keys exposed by Vyne.
Using webhook notifications
When the status of a payment is updated, Vyne will send a digitally signed POST request to the specified callback URL. Make sure you have set up a callback URL.
Webhook
--header 'x-signature=h4DnIgww/Qw0NhMFlzgQuLKpvhVgJGm5ZSImO7wh7MewUX3AJYa06fwh9naN1Zp7h9OopRbVR3oY8L0PzDmirXyX1QM3eRZIkSjAZs+S9vx7D2ETH0WGk3ByJ28i3j6Q3Be3G5PEx91llVgTsOyYTdKVykzh/b8azI+5fr45PMe6mOKVjb8hoBsMJP9n+jQWQ8NnkR9h4iCxxqULFsY+oXu08dFFMPfnyc2Lp7rA66kLZVU7w4XS3rrNxoWV65Z75lvB8wAefWkR9KdFE8kWdZpAqdG+nC78EEZOo3fMoW+RuNKP57rw0yjC0Xmh8fActzTVyKcBlhum+/fTBc8rCbeoFKoHBiXQ+mcTKTdTveVEe2P95jtet6C2AMI0grRo7N45kMPT2IhyFxe4WUtafkpkJhTCu65QliGlQwKnebCQYB4uQUmvTQ8vli8FKjomeGis4KYOkQMA1YAatVF00IThbVVKO3QafVGUfn3Sue6EdNPT8UW8DiQ2UPsAYCI8N+M0YyebQZ48NqAv6Rp0Kz/srxiJc7YiWhLIgmoFe5Kfz+HWrIIZknH66HRhK3AFYocSliWtOH9p6YwaDNZ/M7giW7zjNpjWyRq7uoPLFD9OYZgaC+4vIreL3KTx/eCVHx0yqNajVSYAuMExwrPxoctklGAjuWHEFIRtm6wXqE0='
--header 'x-signature-keyId=718c7272-4e33-466b-8ad8-28fa2c95193f'
{
"type": "PAYMENT_STATUS_CHANGE",
"paymentId": "5da26306860bb993",
"status": "SETTLED",
"timestamp": 1632494853092,
"amount": 1.00,
"currency": "GBP",
"description": "Test payment",
"paymentType": "ONE_OFF",
"bankName": "Santander",
"destinationAccount": "GBP1",
"creationTimestamp": "2021-09-27T11:22:58.203Z",
"updateTimestamp": "2021-09-27T11:22:58.203Z",
"customerReference": "123",
"merchantReference": "ABC",
"refundedAmount": 0.00,
"payerToken": "cc858257-f778-51ed-9c89-8d28dd30ea1a"
}
| Parameter | Description |
|---|---|
| type | A constant type for the payment status notification. |
| paymentId | 16 digit alphanumeric unique payment identifier. |
| status | The current status of the payment. For all possible statuses see here. |
| timestamp | Exact date when the webhook notification was sent represented by a UNIX epoch time in milliseconds. |
| amount | Amount to be paid by the payer. |
| currency | The three-character payment currency using ISO 4217. |
| description (if provided) | An internal description - can be up to 250 characters alphanumeric. |
| paymentType | The type of payment. |
| bankName | The bank from which the payment was initiated. |
| destinationAccount | Specifies the ID of the merchant's destination bank account (e.g. GBP1). |
| customerReference (if provided) | Reference field for customer ID - can be up to 128 characters alphanumeric. |
| merchantReference (if provided) | Reference field for order ID - can be up to 256 characters and alphanumeric. |
| serviceType (if provided) | Distinguishes between EUR connections supporting SCT (standard) and SCT Inst (enhanced) payments. |
| refundedAmount | The amount of the payment that has so far been refunded. |
| creationTimestamp | The time that the payment initiation request was originally made, using ISO 8601. |
| updateTimestamp | The time that the payment status changed, using ISO 8601. |
| payerToken | A pseudonymised representation of the payer's account details as a token (account number/sort code or IBAN). The token is unique to the payer's account. |
DEPRECATED createdAt | The time that the payment initiation request was originally made, in specific UTC time format. |
DEPRECATED updatedAt | The time that the payment status changed, in specific UTC time format. |
Verifying integrity
Every webhook notification sent by Vyne is digitally signed using public key cryptography, also known as asymmetric cryptography, and will allow the merchant verify the origin and the integrity of the message. Learn how to verify the integrity of the webhook notification here.
Using payment status call
You can request a status update on any payment at any time by sending an HTTP GET request to the relevant base URL + /api/v1/payments/ including the headers Authorization: Bearer <payment_token>. You can use the same payment token generated previously.
Request
curl --location --request GET 'https://uat.app.payvyne.com/api/v1/payments/<paymentId>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <payment_token>'
| Parameter | Description |
|---|---|
| paymentId | 16 digit alphanumeric unique payment identifier. |
A successful request returns a 200 response code and an object with details of the payment.
If something unexpected happened during the request, the API returns an error response with the appropriate HTTP status code and a JSON response that contains detailed information about the problem.
Response
{
"id": "b0175ff11f6f5752",
"amount": 1.00,
"currency": "GBP",
"description": "Test payment",
"status": "COMPLETED",
"type": "ONE_OFF",
"destinationAccount": "GBP3",
"creationTimestamp": "2021-09-27T11:22:58.203Z",
"updateTimestamp": "2021-09-27T11:22:58.203Z",
"bank": "Monzo",
"customerReference": "123",
"merchantReference": "ABC",
"refundedAmount": 0.00,
"expiryDateZoned": "2022-08-31T17:19:25.533Z"
}
| Parameter | Description |
|---|---|
| id | 16 digit alphanumeric unique payment identifier. |
| amount | Amount to be paid. |
| currency | The three-character payment currency using ISO 4217. |
| description (if provided) | An internal description - can be up to 250 characters alphanumeric. |
| status | The current status of the payment. For all possible statuses see here. |
| type | The type of payment. |
| destinationAccount | Specifies the ID of the merchant's destination bank account (e.g. GBP1). |
| creationTimestamp | The time that the payment initiation request was originally made, using ISO 8601. |
| updateTimestamp | The time that the payment status changed, using ISO 8601. |
| bank | The bank from which the payment was initiated. |
| customerReference (if provided) | Reference field for customer ID - can be up to 128 characters alphanumeric. |
| merchantReference (if provided) | Reference field for order ID - can be up to 256 characters and alphanumeric. |
| refundedAmount | The amount of the payment that has so far been refunded. |
| expiryDateZoned | The time that the payment will expire if not used, using ISO 8601. |
DEPRECATED createdAt | The time that the payment initiation request was originally made, in specific UTC time format. |
DEPRECATED updatedAt | The time that the payment status changed, in specific UTC time format. |
DEPRECATED expiryDate | The time that the payment will expire if not used, in specific UTC time format. |
Updated about 1 year ago