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). These endpoints are deprecated .

Use of legacy endpoints for new integrations is discouraged where alternative endpoints have been provided.

Payment Request Model deprecated

Attributes

requestId
string

The ID of the Payment Request.
merchantId
string

The ID of the Merchant creating the request.
merchantName
string

The name of the Merchant the Payment Request is on behalf of.
clientId
string

The ID of the merchant specific client configuration.
denomination
monetary

The value of the Payment Request.
payments
array

The Legacy Payment Options
qrCode
string

The URL for a Centrapay webpage that allows the user to pay the Payment Request.
requestCode
string

The URL for a Centrapay webpage that allows the user to pay the Payment Request.
patronCode
string

The id of a Patron Code the payment request is attached to.
status
string

new, paid, cancelled, or expired.
cancellationReason
string

The Cancellation Reason .
createdAt
timestamp

When the Payment Request was created.
updatedAt
timestamp

When the Payment Request was updated.
liveness
string

Indicates liveness of assets that are accepted, determined by the payment options. Values are main or test.
paymentExpirySeconds
string

The expiry seconds used to configure the Payment Request expiry.
terminalId
string

The software or logical id of the payment terminal.
deviceId
string

The hardware id or serial number of the payment terminal.
description
string

A human readable description of the payment.
externalReference
string

An external reference to the Payment Request.
paidBy
string

The payment details. See Paid By .
shortCode
string

A shorter id that can be used to identify the Payment Request for up to two years.
notifyUrl
string

The URL that will receive the webhook POST requests.

Payment Options Model deprecated

Attributes

ledger
string

Related to the Asset Type for the payment. See ledger and authorization values .
amount
number

The amount in the minimum divisible units of the denominated asset that would satisfy the payment.
account
string

The Centrapay Account which the payment should be made to.
methods
string

A collection of methods indicating how the payment can be carried out. Valid values: qr_code.

Paid By Model deprecated

Attributes

transactionId
string

The transaction to refund. The transaction id for a payment can be obtained from a webhook notification or from requests.info .
amount
number

The amount paid.

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
bitcoin.main	g.crypto.bitcoin.mainnet	Bitcoin transaction id

Create a Payment Request deprecated

This endpoint allows you to create a Payment Request.

Attributes

amount
number required

The amount in the minimum divisible units of the denominated asset that would satisfy the payment.
asset
string required

The Asset Type for the payment.
merchantId
string required

The ID of the Merchant creating the request.
clientId
string

The ID of the merchant specific client configuration.
description
string

A human readable description of the payment.
externalReference
string

An external reference to the Payment Request.
notifyUrl
string

The URL that will receive the webhook POST requests.
patronCode
string

The id of a Patron Code the payment request is attached to.
paymentExpirySeconds
string

The expiry seconds used to configure the Payment Request expiry.
terminalId
string

The software or logical id of the payment terminal.
deviceId
string

The hardware id or serial number of the payment terminal.

Errors

CHECKSUM_FAILED
400

patronCode luhn checksum digit doesn’t pass.
PATRON_CODE_INVALID
403

patronCode doesn’t exist or has expired.
MERCHANT_CONFIGURATION_NOT_FOUND
403

There was no merchant configuration found for the supplied merchantId and clientId.
NO_AVAILABLE_PAYMENT_OPTIONS
403

No payment options match the requested payment parameters.

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"
}

Get a Payment Request deprecated

This endpoint allows you to receive Payment Request information.

Attributes

requestId
string required

The payment requestId that is generated when requests.create is called.

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
}

Pay a Payment Request < deprecated

This endpoint allows you to pay a Payment Request.

Attributes

requestId
string required

The payment requestId that is generated when requests.create is called.
ledger
string required

Relates to the Asset Type for the payment. See ledger and authorization values for expected values.
authorization
string required

An identifier that can be used to pay or verify payment. See ledger and authorization values for expected values.

Errors

REQUEST_EXPIRED
403

Action cannot be completed because the request has expired.
REQUEST_PAID
403

Action cannot be completed because the request has been paid.
REQUEST_CANCELLED
403

Action cannot be completed because the request has already been cancelled.
INVALID_ASSET_TYPE
403

The merchant is not configured with the provided asset type.
INACTIVE_ASSET
403

The asset is not spendable. It may have been disabled, expired, or already spent.
INVALID_MERCHANT_CONFIG
403

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.
QUOTA_EXCEEDED
403

The payment pay request exceeds the allowed spend quota supplied.
INSUFFICIENT_ASSET_VALUE
403

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.
ASSET_REDEMPTION_DENIED
403

The asset redemption has been unsuccessful due to an error with provided payment parameters, the merchant, or the asset.

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
}

Cancel a Payment Request deprecated

This endpoint allows you to cancel a Payment Request.

Attributes

requestId
string required

The payment requestId that is generated when requests.create is called.

Errors

REQUEST_NOT_FOUND
400

The provided request doesn’t exist.
REQUEST_EXPIRED
400

Action cannot be completed because the request has expired.
REQUEST_PAID
404

Action cannot be completed because the request has been 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"
}

Void a Payment Request deprecated

This endpoint allows you to void a Payment Request.

Attributes

requestId
string required

The payment requestId that is generated when requests.create is called.

Errors

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.

REQUEST_NOT_FOUND
400

The provided request doesn’t exist.
REQUEST_EXPIRED
400

Action cannot be completed because the request has expired.
REQUEST_PAID
404

Action cannot be completed because the request has been paid.

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"
}

Refund a Transaction deprecated

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.

Attributes

transactionId
string required

The transaction to refund. The transaction id for a payment can be obtained from a webhook notification or from requests.info .
amount
string required

The amount to refund in cents.
externalReference
string

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.

Errors

Attributes

ALREADY_REFUNDED
400

The transaction has already been refunded.
INVALID_AMOUNT
400

The refund requested is greater than the transaction amount.
REPEAT_REFERENCE
400

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.
PARTIAL_REFUNDS_NOT_ALLOWED
403

The asset does not support partial refunds.
INACTIVE_ASSET
403

The asset is not refundable. It may have been disabled, expired, or already refunded.
REFUND_NOT_SUPPORTED
403

The asset type does not support refunds.
REFUND_WINDOW_EXCEEDED
403

The time since the payment exceeds the window of time a transaction can be refunded in.
REFUND_DECLINED
403

The refund parameters were valid but refund was declined because additional business rules were violated.

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
}

Webhooks deprecated

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"
      }
    }
  }
}

Payment Request Model deprecated

Attributes

requestId

merchantId

merchantName

clientId

denomination

payments

qrCode

requestCode

patronCode

status

cancellationReason

createdAt

updatedAt

liveness

paymentExpirySeconds

terminalId

deviceId

description

externalReference

paidBy

shortCode

notifyUrl

Payment Options Model deprecated

Attributes

ledger

amount

account

methods

Paid By Model deprecated

Attributes

transactionId

amount

Ledger and Authorization Values

Create a Payment Request deprecated

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

Get a Payment Request deprecated

Attributes

requestId

Pay a Payment Request < deprecated

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

Cancel a Payment Request deprecated

Attributes

requestId

Errors

REQUEST_NOT_FOUND

REQUEST_EXPIRED

REQUEST_PAID

Void a Payment Request deprecated

Attributes