Go to home page
Docs

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.

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 TypeLedger Param ValueAuthorization Param Value
centrapay.nzd.maincentrapay.nzd.mainCentrapay wallet id
centrapay.nzd.testcentrapay.nzd.testCentrapay wallet id
bitcoin.maing.crypto.bitcoin.mainnetBitcoin transaction id
POST /payments/api/requests.create

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.

Request
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>'
Response
{
  "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 /payments/api/requests.info

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.

Request
curl -X GET \
 'https://service.centrapay.com/payments/api/requests.info?requestId=TyqV56mEkNLUeiY2QskHNR' \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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
}
POST /payments/api/requests.pay

Pay a Payment Request deprecated

This endpoint allows you to pay a Payment Request.

Attributes

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.

Request
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>'
Response
{
  "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
}
POST /payments/api/requests.cancel

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.

Request
curl -X POST \
 'https://service.centrapay.com/payments/api/requests.cancel?requestId=a95b3b0d-1278-4613-8772-20d146065a2e' \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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"
}
POST /payments/api/requests.void

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.

Request
curl -X POST \
 'https://service.centrapay.com/payments/api/requests.void?requestId=a95b3b0d-1278-4613-8772-20d146065a2e' \
 -H 'x-api-key: <TOKEN>'
Response
{
  "type": "voidCancel",
  "status": "Success",
  "message": "string"
}
POST /payments/api/transactions.refund

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.

Request
curl -X POST \
 'https://service.centrapay.com/payments/api/transactions.refund?transactionId=7d2b1d52-b609-4ccd-b4cc-c4a9af881bd9&amount=100' \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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 TypeValue of “transactionType”
Payment Request CancelledCANCELLED
Payment Request ExpiredEXPIRED
Transaction CompletedPURCHASE
Transaction RefundedREFUND

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

PropertyDescription
transactionIdId of the transaction
transactionTypeIndicates which event triggered the notification message
stateCurrent state of the transaction
ledgerThe ledger at which the authorization was processed
amountTransaction amount in the lowest denomination available
createdAtTimestamp at which the request was created
updatedAtTimestamp at which the request was updated
typeThe payment type used by the issuer to reconcile settlement
requestRequest object, see details at [requests.info][]
authCodeAuthorization 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"
      }
    }
  }
}