Legacy Payment Requests
Centrapay Payment Requests are serviced via two sets of endpoints; the “next” version (documented Payment Requests) and the “legacy” version (documented on this page). Use of legacy endpoints for new integrations is discouraged where alternative endpoints have been provided.
Legacy Payment Request endpoints also have interactive Swagger documentation.
Contents
Operations
Creating a payment request
POST /
curl -X POST https://service.centrapay.com/payments/api/requests.create \
-H "X-Api-Key: $api_key" \
-d merchantId=5efbe17d96c083633e2b9241 \
-d clientId=5efbe2fb96c08357bb2b9242 \
-d amount=300 \
-d asset=NZD
Required Parameters
Parameter | Description |
---|---|
amount | The payment amount in cents |
asset | The currency code (e.g. ‘NZD’) |
merchantId | The id of the merchant creating the request |
clientId | The id of the merchant specific client configuration |
See Asset Types for the list of possible asset
values for each Asset Type.
Optional Parameters
Parameter | Description |
---|---|
description | Description of the payment |
externalReference | Unique merchant reference for the payment request |
notifyUrl | The URL that will receive POST requests from the webhook |
paymentExpirySeconds | The amount of seconds until a request expires, must be an integer greater than 0 and less than 86400 (24 hours) |
terminalId | The payment system terminal Id. Required for NZ Epay integration. |
deviceId | Physical payment system device Id |
patronCode | Associate this payment request with an active Patron Code. |
Error Responses
Status | Code | Description |
---|---|---|
400 | CHECKSUM_ | patronCode luhn checksum digit doesn’t pass. |
403 | PATRON_ | patronCode doesn’t exist or has expired. |
403 | MERCHANT_ | There was no merchant configuration found for the supplied merchantId and clientId. |
403 | NO_ | No payment options match the requested payment parameters. |
Getting the information about a payment request
GET /
curl -G https://service.centrapay.com/payments/api/requests.info \
-H "X-Api-Key: $api_key" \
-d requestId=TyqV56mEkNLUeiY2QskHNR
Required Parameters
Parameter | Description |
---|---|
requestId | The payment requestId that is generated when requests.create is called |
Error Responses
Http code | Error code | Message | Description |
---|---|---|---|
404 | 2 | REQUEST_ | The provided request doesn’t exist. |
Example response payload of a new request
{
"requestId": "TyqV56mEkNLUeiY2QskHNR",
"shortCode": "CP-C7F-ZS5",
"merchantId": "5efbe17d96c083633e2b9241",
"merchantName": "NZD Test Merchant",
"clientId": "5efbe2fb96c08357bb2b9242",
"denomination": {
"asset": "NZD",
"amount": 100
},
"payments": [
{
"ledger": "centrapay.nzd.test",
"amount": 100,
"methods": [
"qr_code"
]
}
],
"qrCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
"requestCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
"status": "new",
"createdAt": "2021-11-29T23:04:54.253Z",
"updatedAt": "2021-11-29T23:04:54.253Z",
"liveness": "test",
"paymentExpirySeconds": 120
}
Example response payload of a paid request
{
"requestId": "TyqV56mEkNLUeiY2QskHNR",
"shortCode": "CP-C7F-ZS5",
"merchantId": "5efbe17d96c083633e2b9241",
"merchantName": "NZD Test Merchant",
"clientId": "5efbe2fb96c08357bb2b9242",
"denomination": {
"asset": "NZD",
"amount": 100
},
"payments": [
{
"ledger": "centrapay.nzd.test",
"amount": 100,
"methods": [
"qr_code"
]
}
],
"qrCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
"requestCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
"status": "paid",
"createdAt": "2021-11-29T23:04:54.253Z",
"updatedAt": "2021-11-29T23:05:38.254Z",
"liveness": "test",
"paymentExpirySeconds": 120,
"paidBy": {
"ledger": "centrapay.nzd.test",
"type": "centrapay.nzd.test",
"authCode": "3MhaANvdS79qhvAj6nYFNT",
"responseCode": "1234",
"receipt": "",
"v2": true,
"paidAt": "2021-11-29T23:05:38.000Z",
"amount": 100,
"account": "3MhaANvdS79qhvAj6nYFNT",
"transactionId": "TyqV56mEkNLUeiY2QskHNR",
"description": "Centrapay Test NZD",
"settlementDate": "2021-11-29T23:05:38.000Z",
"assetTotals": [
{
"type": "centrapay.nzd.test",
"description": "Centrapay Test NZD",
"settlementDate": "2021-11-29T23:05:38.000Z",
"total": {
"amount": "100",
"currency": "NZD"
}
}
]
}
}
Paying a payment request
POST /
curl -X POST https://service.centrapay.com/payments/api/requests.pay \
-H "X-Api-Key: $api_key" \
-d authorization=12345678 \
-d ledger=g.pocketvouchers.pv \
-d requestId=7d2b1d52-b609-4ccd-b4cc-c4a9af881bd9
Required Parameters
Parameter | Description |
---|---|
requestId | The id of the payment request to pay. See requests.create. |
ledger | The selected payment option to use. See below for expected values. |
authorization | An identifier that can be used to pay or verify payment. See below for expected values. |
Expected Ledger and Authorization Values
The “ledger” parameter indicates which payment option has been selected to pay the payment request. The selected payment option must be one of the options available for the payment request as per the payments
array in the requests.create and requests.info responses.
The table below lists the possible ledger and authorization param values. The asset type is the value used to configure the merchant. The ledger param value is returned with the payment request info as payments[].ledger
.
Asset Type | Ledger Param Value | Authorization Param Value |
---|---|---|
centrapay.nzd.main | centrapay.nzd.main | Centrapay wallet id |
centrapay.nzd.test | centrapay.nzd.test | Centrapay wallet id |
epay.nzd.main | epay.nzd.main | Centrapay asset id |
pocketvouchers | g.pocketvouchers.pv | Pocket Vouchers voucher code |
bitcoin.main | g.crypto.bitcoin.mainnet | Bitcoin transaction id |
cennznet.main | cennznet.main | Cennznet transaction id |
zap.main | zap.main | Waves transaction id |
test | g.test.testUplink | Any |
Centrapay Asset Permissions
To pay with a Centrapay asset or wallet ledger the user (identified by the API Key or identity token) must have permission to redeem the asset or transfer funds from the specified wallet.
Testing Pocket Vouchers
To test Pocket Vouchers, generate a test value voucher by texting “CENTRALBONUS” to 393. You will then receive a response text containing an 8 digit voucher code that has $20 of loaded credit. The received code is only valid for two weeks from the issue date. You might get charged your standard text rates from your provider.
Error Responses
Http code | Message | Description |
---|---|---|
403 | REQUEST_ | Action cannot be completed because the request has expired. |
403 | REQUEST_ | Action cannot be completed because the request has been paid. |
403 | REQUEST_ | Action cannot be completed because the request has already been cancelled. |
403 | INVALID_ | The merchant is not configured with the provided asset type. |
403 | INACTIVE_ | The asset is not spendable. It may have been disabled, expired, or already spent. |
403 | INVALID_ | The merchant is not configured properly to satisfy the payment request. This could be due to incorrect information, or the merchant’s credentials might be blocked by an external service. |
403 | QUOTA_ | The payment pay request exceeds the allowed spend quota supplied. |
403 | INSUFFICIENT_ | The asset has insufficient funds to pay the payment request or the transaction amount received by Centrapay is less than the total of the payment. |
403 | ASSET_ | The asset redemption has been unsuccessful due to an error with provided payment parameters, the merchant, or the asset. |
Cancelling a payment request
POST /
curl -X POST https://service.centrapay.com/payments/api/requests.cancel \
-H "X-Api-Key: $api_key" \
-d requestId=a95b3b0d-1278-4613-8772-20d146065a2e
Required Parameters
Parameter | Description |
---|---|
requestId | The payment requestId that is generated when requests.create is called |
Error Responses
Http code | Error code | Message | Description |
---|---|---|---|
404 | 2 | REQUEST_ | The provided request doesn’t exist. |
400 | 18 | REQUEST_ | Action cannot be completed because the request has expired. |
400 | 19 | REQUEST_ | Action cannot be completed because the request has been paid. |
Voiding a payment request
POST /
curl -X POST https://service.centrapay.com/payments/api/requests.void \
-H "X-Api-Key: $api_key" \
-d requestId=a95b3b0d-1278-4613-8772-20d146065a2e
Required Parameters
Parameter | Description |
---|---|
requestId | The payment requestId that is generated when requests.create is called. |
Error Responses
Http code | Error code | Message | Description |
---|---|---|---|
404 | 2 | REQUEST_ | The provided request doesn’t exist. |
403 | VOID_ | The amount of time since the payment request was created exceeds the window of time a payment request can be voided (24 hours). |
Voiding a payment request can cause it to be cancelled or refunded. Therefore, this endpoint can give the same error responses as requests.cancel and transactions.refund. After 24 hours voiding a payment request will be disallowed, however a refund can still be made against the payment request if it has been paid successfully.
Refunding a transaction
POST /
curl -X POST https://service.centrapay.com/payments/api/transactions.refund \
-H "X-Api-Key: $api_key" \
-d transactionId=7d2b1d52-b609-4ccd-b4cc-c4a9af881bd9 \
-d amount=100
Refunding a transaction can be done with or without an external reference.
Refund without external reference
If you refund a transaction without providing an external reference, you will get a successful response for the first request and then an ALREADY_REFUNDED message for any refund requests that follow for the same transaction, unless an external reference is provided.
Refund with external reference
If you provide an external reference then a transaction can be refunded multiple times provided that the external reference is unique for each refund request. When a duplicate external reference is provided when attempting to refund the same transaction we return a successful response if the amount of the request is the same both times but do not process another refund, this is because we assume it to be a repeat request. If the amount is different you will get a REPEAT_REFERENCE error message.
Refund a Pre Auth Payment Request with Confirmations
The legacy refund endpoint cannot be used to refund Pre Auth Payment Requests with Confirmations. Please use the current refund endpoint instead.
Required Parameters for one time refund
Parameter | Description |
---|---|
transactionId | The transaction to refund. The transaction id for a payment can be obtained from a webhook notification or from requests.info. |
amount | The amount to refund in cents |
Additional required Parameter for multiple refunds
Parameter | Description |
---|---|
externalReference | A reference supplied by the merchant that must be unique for each refund of that transaction, can be anything you want but it must be unique. |
Error Responses
Http code | Error code | Message | Description |
---|---|---|---|
404 | 3 | TRANSACTION_ | The provided transaction doesn’t exist. |
400 | 276 | ALREADY_ | The transaction has already been refunded. |
400 | 277 | INVALID_ | The refund requested is greater than the transaction amount. |
400 | 280 | REPEAT_ | A separate refund request for the same transaction has the same external reference, trying to refund the same transaction twice with the same external reference is not allowed. If the amount of the refund is the same we assume it is a repeat request and return 200. |
403 | 281 | PARTIAL_ | The asset does not support partial refunds. |
403 | 283 | INACTIVE_ | The asset is not refundable. It may have been disabled, expired, or already refunded. |
403 | REFUND_ | The asset type does not support refunds. | |
403 | REFUND_ | The time since the payment exceeds the window of time a transaction can be refunded in. |
Webhooks
Webhook notifications are sent for significant Payment life-cycle events. The Webhook endpoint is notified by sending an HTTP POST request to the notifyUrl
defined in the Payment Request.
Life-cycle Events That Trigger Webhooks
The supported event types that will be notified to the Payment Requests webhook and the associated “transactionType” value that will be sent in the payload are:
Event Type | Value of “transactionType” |
---|---|
Payment Request Cancelled | CANCELLED |
Payment Request Expired | EXPIRED |
Transaction Completed | PURCHASE |
Transaction Refunded | REFUND |
Payment Request Cancelled
A payment request can be cancelled by either calling the requests.cancel or requests.void endpoint before a request has been paid successfully. When a request has been cancelled we send a JWT that when decoded matches the Payment Request Cancelled example in the Decoded Webhook JWT Examples section below.
Payment Request Expired
A payment request expires two minutes after being created if it hasn’t been cancelled, or paid. When a request has expired we send a JWT that when decoded matches the Payment Request Cancelled example in the Decoded Webhook JWT Examples section below with the transactionType
set to EXPIRED.
Transaction Completed
A transaction is considered complete when requests.pay is called with parameters that satisfy a payment request and the request has been paid successfully. When a transaction has been completed we send a JWT that when decoded matches the Transaction Completed example in the Decoded Webhook JWT Examples section below.
Transaction Refunded
A transaction can be refunded one to many times and each time a transaction has been refunded successfully we notify the webhook associated with the original payment request. A transaction can be refunded when transactions.refund has been called for a partial or full refund, or when requests.void is called for a request that has been paid. When a transaction has been refunded we send a JWT that when decoded matches the Transaction Completed example in the Decoded Webhook JWT Examples section below but with transactionType
set to REFUND.
Webhook Payload
The body of the webhook is a JSON document with the following format:
{
"token": "${JWT}"
}
The decoded JWT will contain a “transaction” property with a “transactionType” that indicates the event type. Depending on the type of event, the payload will also contain additional details about the transaction and payment request. For example:
{
"transaction": {
"transactionType": "REFUND",
"request": {
"requestId": "bec358bf-edb5-4633-a785-a95cc281d3b7",
"denomination": {
"asset": "NZD",
"amount": "100"
}
}
}
}
Webhook Payload Fields
Property | Description |
---|---|
transactionId | Id of the transaction |
transactionType | Indicates which event triggered the notification message |
state | Current state of the transaction |
ledger | The ledger at which the authorization was processed |
amount | Transaction amount in the lowest denomination available |
createdAt | Timestamp at which the request was created |
updatedAt | Timestamp at which the request was updated |
type | The payment type used by the issuer to reconcile settlement |
request | Request object, see details at requests.info |
authCode | Authorization code used to settle this transaction |
Webhook JWT Validation
A webhook JWT can be validated by checking the signature against the Centrapay Webhook public key:
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt+vW2fE0mLLmdzJtYrz7J9q/yEXl
gmIjCXdv3VNvYfTsaBO5PJNiaD3l9lD8PzEQu31ePsOG81mDVuo40+dgLg==
-----END PUBLIC KEY-----
Decoded Webhook JWT Examples
Transaction Completed Successfully
{
"transaction": {
"transactionId": "E6ctbmgmkgZ3xnPk3BkGvb",
"transactionType": "PURCHASE",
"ledger": "g.crypto.bitcoin.mainnet",
"state": "completed",
"amount": 2000,
"request": {
"requestId": "0FmbuirpQG4iuy6xAV9R1p",
"merchantId": "613919a417bea000290e97e3",
"externalReference": "12345sixseveneightnineten",
"denomination": {
"asset": "NZD",
"amount": 2000
}
},
"createdAt": "2018-10-02T00:29:09.307Z",
"updatedAt": "2018-10-02T00:29:11.383Z",
"type": "BITCOIN",
"authCode": "961241"
}
}
Payment Request Cancelled
{
"transaction": {
"transactionType": "CANCELLED",
"request": {
"requestId": "0FmbuirpQG4iuy6xAV9R1p",
"merchantId": "613919a417bea000290e97e3",
"clientId": "613919a417bea000290e97e4",
"denomination": {
"asset": "NZD",
"amount": "1"
}
}
}
}