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 deprecated.
Use of legacy endpoints for new integrations is discouraged where alternative endpoints have been provided.
Attributes
requestId
stringmerchantId
stringmerchantName
stringclientId
stringdenomination
monetarypayments
arrayqrCode
stringrequestCode
stringpatronCode
stringstatus
stringcancellationReason
stringcreatedAt
timestampupdatedAt
timestampliveness
stringpaymentExpirySeconds
stringterminalId
stringdeviceId
stringdescription
stringexternalReference
stringpaidBy
stringshortCode
stringnotifyUrl
string
Attributes
ledger
stringamount
numberaccount
stringmethods
string
Attributes
transactionId
stringamount
number
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 |
bitcoin.main | g.crypto.bitcoin.mainnet | Bitcoin transaction id |
This endpoint allows you to create a Payment Request.
Attributes
amount
numberrequiredasset
stringrequiredmerchantId
stringrequiredclientId
stringdescription
stringexternalReference
stringnotifyUrl
stringpatronCode
stringpaymentExpirySeconds
stringterminalId
stringdeviceId
string
Errors
CHECKSUM_FAILED
400PATRON_CODE_INVALID
403MERCHANT_CONFIGURATION_NOT_FOUND
403NO_AVAILABLE_PAYMENT_OPTIONS
403
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
stringrequired
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
stringrequiredledger
stringrequiredauthorization
stringrequired
Errors
REQUEST_EXPIRED
403REQUEST_PAID
403REQUEST_CANCELLED
403INVALID_ASSET_TYPE
403INACTIVE_ASSET
403INVALID_MERCHANT_CONFIG
403QUOTA_EXCEEDED
403INSUFFICIENT_ASSET_VALUE
403ASSET_REDEMPTION_DENIED
403
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
stringrequired
Errors
REQUEST_NOT_FOUND
400REQUEST_EXPIRED
400REQUEST_PAID
404
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
stringrequired
Errors
REQUEST_NOT_FOUND
400REQUEST_EXPIRED
400REQUEST_PAID
404
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
stringrequiredamount
stringrequiredexternalReference
string
Errors
Attributes
ALREADY_REFUNDED
400INVALID_AMOUNT
400REPEAT_REFERENCE
400PARTIAL_REFUNDS_NOT_ALLOWED
403INACTIVE_ASSET
403REFUND_NOT_SUPPORTED
403REFUND_WINDOW_EXCEEDED
403REFUND_DECLINED
403
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"
}
}
}
}