Recurring payment status updates

Receive updates on recurring payments as their status changes

The time it takes a bank to process a RPIRRPIR - Recurring Payment Initiation Request can vary and may not be instant. Because of this, Vyne provides updates when the status of a recurring payment changes.

There are different methods to obtain the status of the recurring 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 success or failure message (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 payment status

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.

Approach 1: Callback URL payload

After the consumer authorises the payment at their bank, you should direct them to a confirmation page. For every RPIRRPIR - Recurring Payment Initiation Request, 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 JWT token.

Encoded URL

https://merchant.site?payvyne_payment_payload=eyJraW...5MwvsUjZpqY7p_jZo

Body

{
  "kid": "aeaf334e-9a54-41e8-961a-e3838081fd5c",
  "alg": "RS256"
}
{
  "jti": "46406996-1a33-4eef-a891-25077a576676",
  "iss": "http://app.payvyne.com",
  "sub": "payment_info",
  "paymentStatus": "COMPLETED",
  "paymentId": "787fd82e5578fc3b",
  "iat": 1608226143,
  "exp": 1608227943
}

Token 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.

Approach 2: Webhook status updates

When the status of a recurring 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.

Response

--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": "762b72a84b7541f2",
  "status": "SENT", 
  "timestamp": 1608626647021
}

Parameter

Description

type

A constant type for the payment status notification.

paymentId

16 digit long, alphanumeric unique identifier.

status

The new status of the payment. For all possible statuses see here.

timestamp

Exact date when the update happened represented by a UNIX epoch time in milliseconds.

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.

Approach 3: Get request status

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>. Generate a fresh payment token for the <payment_token>.

Request

curl --location --request GET 'https://uat.app.payvyne.com/api/v1/payments/<paymentId>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <payment_token>'

Request parameters

Parameter

Description

paymentId

The requestId from the initiation response

Response

{
    "id": "14d8c2ac37c1811f",
    "amount": "5",
    "currency": "GBP",
    "description": "Payment from iOS Sample App",
    "status": "INITIATED",
    "type": "ONE_OFF",
    "createdAt": "2020-05-28T12:55:56.253",
    "updatedAt": "2020-05-28T12:55:57.383",
    "destinationAccount": "GBP1",
    "bank": "Monzo",
    "customerReference": "hgd768j2ui1k"
}

Request statuses

Recurring payment requests can be in one of many statuses which reflect the stage in the process the payment has reached between Vyne and the bank. Find out more about payment statuses here.

📘

Helpful to know

The latest API keys can be found at the relevant base URL + /api/keys/.

Choosing the right key for verification is done by using the kid (key ID) attribute from both the JWT header and the exposed keys.


What’s Next

Now you've successfully got updates for your recurring payment requests, learn how to test your integration.

Did this page help you?