Centrapay Payment Requests are serviced via two sets of endpoints; the “next” version (documented Payment Requests API ) and the “legacy” version (documented on this page). These endpoints are .
Use of legacy endpoints for new integrations is discouraged where alternative endpoints have been provided.
Attributes
Attributes
ledger
amount
account
methods
productCodes
Attributes
transactionId
amount
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 |
bitcoin.main | g.crypto.bitcoin.mainnet | Bitcoin transaction id |
This endpoint allows you to create a Payment Request.
Attributes
amount
asset
merchantId
clientId
description
externalReference
notifyUrl
patronCode
paymentExpirySeconds
terminalId
deviceId
Errors
CHECKSUM_FAILED
PATRON_CODE_INVALID
MERCHANT_CONFIGURATION_NOT_FOUND
NO_AVAILABLE_PAYMENT_OPTIONS
curl -X POST \
'https://service.centrapay.com/payments/api/requests.create?merchantId=b0792018-6efc-4bca-a148-83bc57ff75b9&clientId=b80c361f-805a-405c-b0af-366d3b5bd4ef&amount=300&asset=NZD' \
-H 'x-api-key: <TOKEN>'
{
"clientId": "b80c361f-805a-405c-b0af-366d3b5bd4ef",
"denomination": {
"amount": 350,
"asset": "NZD"
},
"notifyUrl": "http://example.com/payments/api/service.notify",
"payments": [
{
"account": "bc1qs3z0uh5e9k9tlhcswqg76vxkewjsjq2htlpv2f",
"amount": 0.0027625,
"ledger": "g.crypto.bitcoin.mainnet",
"methods": [
"qr_code"
]
}
],
"qrCode": "cp_9e98c00c-1556-4c95-ba78-2dd1fc97fc5b",
"status": "new",
"paidBy": {
"transactionId": "d52cc472-613c-4f25-ae2d-e880a0a24646",
"amount": 1020
},
"description": "Coffee",
"externalReference": "03.01.09.chancellor",
"merchantId": "b0792018-6efc-4bca-a148-83bc57ff75b9",
"requestId": "9e98c00c-1556-4c95-ba78-2dd1fc97fc5b",
"createdAt": "2019-12-10T22:30:51.500Z",
"updatedAt": "2019-12-10T22:31:04.983Z"
}
This endpoint allows you to receive Payment Request information.
Attributes
requestId
curl -X GET \
'https://service.centrapay.com/payments/api/requests.info?requestId=TyqV56mEkNLUeiY2QskHNR' \
-H 'x-api-key: <TOKEN>'
{
"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
}
This endpoint allows you to pay a Payment Request.
Attributes
requestId
ledger
authorization
Errors
REQUEST_EXPIRED
REQUEST_PAID
REQUEST_CANCELLED
INVALID_ASSET_TYPE
INACTIVE_ASSET
INVALID_MERCHANT_CONFIG
QUOTA_EXCEEDED
INSUFFICIENT_ASSET_VALUE
ASSET_REDEMPTION_DENIED
curl -X POST \
'https://service.centrapay.com/payments/api/requests.pay?authorization=4a936ad82d8e51ae0afc317e944bfa569d935a45206b49b67117ee8aaa04a3b1&ledger=g.crypto.bitcoin.mainnet&requestId=7d2b1d52-b609-4ccd-b4cc-c4a9af881bd9' \
-H 'x-api-key: <TOKEN>'
{
"createdAt": "2019-12-10T22:30:51.500Z",
"currencyExchange": {
"asset": "BTC",
"rate": 0.000081
},
"merchant": {
"categoryCode": "7372",
"id": "b0792018-6efc-4bca-a148-83bc57ff75b9",
"location": "NZ",
"name": "Centrapay"
},
"payment": {
"amount": 350,
"asset": "NZD",
"message": "Payment processed"
},
"reference": "252e5e22-4b99-4108-90a8-228312c455a7",
"settlementDate": "2019-12-10",
"status": "Success",
"type": "txBitcoin",
"version": 1
}
This endpoint allows you to cancel a Payment Request.
Attributes
requestId
Errors
REQUEST_NOT_FOUND
REQUEST_EXPIRED
REQUEST_PAID
curl -X POST \
'https://service.centrapay.com/payments/api/requests.cancel?requestId=a95b3b0d-1278-4613-8772-20d146065a2e' \
-H 'x-api-key: <TOKEN>'
{
"merchantName": "Coffee Shop",
"status": "cancelled",
"denomination": {
"amount": 350,
"asset": "NZD"
},
"createdAt": "2019-12-10T22:30:51.500Z",
"updatedAt": "2019-12-10T22:31:04.983Z",
"externalReference": "03.01.09.chancellor",
"requestId": "a95b3b0d-1278-4613-8772-20d146065a2e",
"merchantId": "b0792018-6efc-4bca-a148-83bc57ff75b9",
"description": "Coffee"
}
This endpoint allows you to void a Payment Request.
Attributes
requestId
Errors
REQUEST_NOT_FOUND
REQUEST_EXPIRED
REQUEST_PAID
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.
curl -X POST \
'https://service.centrapay.com/payments/api/requests.void?requestId=a95b3b0d-1278-4613-8772-20d146065a2e' \
-H 'x-api-key: <TOKEN>'
{
"type": "voidCancel",
"status": "Success",
"message": "string"
}
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 API instead.
Attributes
transactionId
amount
externalReference
Errors
Attributes
ALREADY_REFUNDED
INVALID_AMOUNT
REPEAT_REFERENCE
PARTIAL_REFUNDS_NOT_ALLOWED
INACTIVE_ASSET
REFUND_NOT_SUPPORTED
REFUND_WINDOW_EXCEEDED
curl -X POST \
'https://service.centrapay.com/payments/api/transactions.refund?transactionId=7d2b1d52-b609-4ccd-b4cc-c4a9af881bd9&amount=100' \
-H 'x-api-key: <TOKEN>'
{
"createdAt": "2019-12-10T22:30:51.500Z",
"currencyExchange": {
"asset": "BTC",
"rate": 0.000081
},
"merchant": {
"categoryCode": "7372",
"id": "b0792018-6efc-4bca-a148-83bc57ff75b9",
"location": "NZ",
"name": "Centrapay"
},
"payment": {
"amount": 350,
"asset": "NZD",
"message": "Payment processed"
},
"reference": "252e5e22-4b99-4108-90a8-228312c455a7",
"settlementDate": "2019-12-10",
"status": "Success",
"type": "txRefund",
"version": 1
}
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": {
"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"
}
}
{
"transaction": {
"transactionType": "CANCELLED",
"request": {
"requestId": "0FmbuirpQG4iuy6xAV9R1p",
"merchantId": "613919a417bea000290e97e3",
"clientId": "613919a417bea000290e97e4",
"denomination": {
"asset": "NZD",
"amount": "1"
}
}
}
}