Take a single payment

Get started

Taking a single payment as a Partner account follows the same approach as taking a single payment for a Merchant account, but uses separate endpoints and additional parameters. Start by familiarising yourself with single payments, including how to request and get status updates for single payments.

Once you're familiar with the process, you can recreate the steps with some minor differences.

📘

Helpful to know

You'll need to generate a partner access token. Learn how to do this in the Partner portal here.

Partner payment requests

Create a PIR. Send an HTTP POST request to the relevant endpoint + /api/v1/partners/payments/ including the header Authorization: Bearer <payment_token>.

In addition to the standard PIR parameters, you must include an additional parameter merchant.

Request

JSON

{
  "merchantId": "1f7rhste5rj0unf6",  	
  "amount": "5.95",
  "currency": "GBP",
  "destinationAccount": "GBP1",
  "description": "Web payment",
  "callbackUrl": "yoursite.com/payment-outcome-page",
  "mediaType": "URL",
  "countries": ["GB"],
  "customerReference": "P739570946",
  "merchantReference": "76FG7JQ",
  "expiration": {
    "unit": "DAYS",
    "value": 1
    }
}

Parameter	Description
merchant	16 digit alphanumeric merchant identifier - used to signify the Merchant account you wish to request payment for.

Response

JSON

{
  "redirectUrl": "<redirect_url>",
  "qrCodeUrl": "<qr_code_url>",
  "requestId": "adca2b6a077de1f5",
  "mediaType": "URL"
}

Using partner webhook notifications

The payment status webhook includes an additional merchant parameter in the body to identify the Merchant account the payment relates to.

Response

JSON

{
  "type": "PAYMENT_STATUS_CHANGE",
  "merchant": "1f7rhste5rj0unf6",
  "paymentId": "5da26306860bb993",
  "status": "SETTLED",
  "timestamp": 1632494853092,
  "amount": 1.00,
  "currency": "GBP",
  "description": "Test payment",
  "paymentType": "ONE_OFF",
  "bankName": "Santander",
  "destinationAccount": "GBP1",
  "creationTimestamp": "2021-09-24T14:47:22.764Z",
  "updateTimestamp": "2021-09-24T14:47:33.092Z",
  "customerReference": "123",
  "merchantReference": "ABC",
  "refundedAmount": 0.00,
  "payerToken": "cc858257-f778-51ed-9c89-8d28dd30ea1a"
}

Parameter	Description
merchant	16 digit alphanumeric merchant identifier of the Merchant account the payment was requested for.

👍

Try it out

Make sure you setup a callback URL in your Partner account to receive webhook notifications for payments made from your account for any linked Merchant accounts.

Using partner payment status calls

You can request a payment status update on any payment at any time by sending an HTTP GET request to the relevant base URL + /api/v1/partners/payments/ including the headers Authorization: Bearer <payment_token>.

Responses will include an additional merchant parameter in the body to identify the Merchant account the payment relates to.

Request

cURL

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

Response

JSON

{
    "merchant": "1f7rhste5rj0unf6", 
    "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": "jgdw74jg",
    "merchantReference": "yegdt6t67g",
    "refundedAmount": "0.00",
    "expiryDateZoned": "2022-08-31T17:19:25.533Z"
}

Parameter	Description
merchant	16 digit alphanumeric merchant identifier of the Merchant account the payment was requested for.

Using partner payer details webhook notifications

If enabled for any of your Merchant accounts, details of the payer's account will be sent upon confirmation of funds received. Follow the instructions to setup webhook notifications for payer details here.

The payer account details webhook will include an additional merchant parameter in the body to identify the Merchant account the payment relates to.

JSON

{
  "type": "PAYER_DETAILS",
  "paymentId": "628eeb4cc58f60a4",
  "merchant": "4c5539c128022dea",
  "payerName": "Jane Bloggs",
  "accountDetails": {
    "iban": "LT34 3250 0909 3475 7655",
    "accountType": "IBAN"
  },
  "timestamp": 1654694419857
}

Parameter	Description
merchant	16 digit alphanumeric merchant identifier of the Merchant account the payment was requested for.