Link Search Menu Expand Document
Centrapay Docs

Payment Requests

Payment Requests represent the intention for a merchant to receive payment for goods and services. Payment Requests define the amount to be paid and the asset types that are acceptable for payment.

A Payment Request is shared with, and paid by, a patron. The Payment Flows Guide has more details regarding negotiation of Payment Requests.

Payment Requests have the following statuses:

  • new: after being created.
  • paid: after being paid with one or more transactions.
  • cancelled: after being cancelled or voided by the merchant.
  • expired: after expiry time is reached without being paid or cancelled.

Payment requests can also be refunded for a short period of time after being paid.

Payment request state transitions can be notified to webhooks.

Centrapay Payment Requests are serviced via two sets of endpoints; the “next” version (documented on this page) and the “legacy” version (documented at Legacy Payment Requests).

Contents

Models

Payment Request

Mandatory Fields

Field Type Description
id String The payment request id.
shortCode String A shorter id that can be used to identify the payment request for up to two years.
url String The URL for a Centrapay webpage that allows the user to pay the Payment Request.
value Monetary The canonical value of the payment request. Must be positive.
paymentOptions Array The Payment Options, indicating valid asset for payment.
merchantId String The id of the Merchant the Payment Request is on behalf of.
merchantName String The name of the Merchant the Payment Request is on behalf of.
configId String The Merchant Config id used to configure the payment options.
status String “new”, “paid”, “cancelled”, or “expired”.
liveness String Indicates liveness of assets that are accepted, determined by the payment options. Values are “main” or “test”.
createdAt Timestamp When the payment request was created.
updatedAt Timestamp When the payment request was updated.
expiresAt Timestamp When the payment request expires.
merchantConditions Array A dynamic list of Payment Conditions that require operator approval to complete a payment. Conditions are calculated when polling a Payment Request.

Optional Fields

Field Type Description
patronCodeId String The id of a Patron Code the payment request is attached to.
barcode String Scanned Code used to create the payment request.
expirySeconds Number The expiry seconds used to configure the payment request expiry.
lineItems Array EXPERIMENTAL The Line Items being paid for.
purchaseOrderRef String A reference to a purchase order for this payment request.
invoiceRef String A reference to an invoice for this payment request.
redirectUrl String Experimental URL to redirect the user to after they pay or cancel the Payment Request. Must start with one of the allowedRedirectUrls for the Merchant Config.
externalRef String An external reference to the payment request
terminalId String The software or logical id of the payment terminal.
deviceId String The hardware id or serial number of the payment terminal.
operatorId String POS operator Id.
createdByAccountId String Id of the Centrapay Account creating the Payment Request.
createdByAccountName String Name of the Centrapay Account creating the Payment Request.
conditionsEnabled Boolean Flag to indicate that a merchant is able to accept Payment Conditions.
patronNotPresent Boolean Flag to indicate the patron is not physically present. This may affect payment conditions or available Payment Options.
cancellationReason String The reason that the payment request was cancelled. See Cancellation Reasons for possible values.
preAuth Boolean Flag to indicate the if the request is a Pre Auth for supported Asset Types.
preAuthExpiresAt Timestamp Pre Auth completions and releases will be accepted until this time.
preAuthStatus String Describes which state a Pre Auth Payment Request is in. Valid values are “authorized”, or “released”.
taxNumber Tax Number The value-added tax configuration for the Business that the Merchant belongs to.

Payment Option

Mandatory Fields

Field Type Description
assetType String An Asset Type reference.
amount BigNumber The value required to pay using the canonical units for the asset type.

Optional Fields

Field Type Description
bitcoinAddress String ★ Address to send Bitcoin, when the “assetType” is bitcoin.*
cennzAddress String ★ Address to send CPay, when the “assetType” is cennznet.*
wavesAddress String ★ Waves address to send Zap tokens, when the “assetType” is zap.*
productCodes Array Supported product codes for the payment request, when the “assetType” is epay.nzd.*

★ For payment options which specify an address, there’s a requirement to make a transaction on an external ledger. Once you have made that payment, you can use the transaction id to Pay a Payment Request using the legacy payment API.

Payment Condition

Some Asset Types require conditional approval to pay. Possible Payment Conditions include confirming proof of ID or confirming a promotional item was purchased.

The conditionsEnabled flag should be set to true when Creating a Payment Request to indicate that Payment Conditions can be accepted. If a Payment Condition arises, the absence of the conditionsEnabled flag will result in the Payment Request being cancelled.

Conditions can either be accepted or declined. If a condition is declined, the Payment Request will be cancelled.

Fields

Name Type Description
id BigNumber An enumerated identifier for the Payment Condition.
name String The name of the condition.
message String The human-readable description of the condition.
status String The status of the condition. Valid values include accepted, declined, awaiting-merchant or void.

Line Item

An order item for which payment is requested. The currency and units for a line item price will be consistent with the payment request value and the sum of line item prices should equal the payment request value.

Line items can include a discount amount. A discount that applies to multiple line items may be represented as a separate line item with a negative amount.

Mandatory Fields

Field Type Description
name String The product description.
sku String The product (stock keeping unit) code.
qty BigNumber The product quantity (eg. item count, weight, volume etc).
price BigNumber The total price in cents for the line item (eg. price = product price * qty - discounts + tax).

Optional Fields

Field Type Description
tax BigNumber Tax rate (percentage).
discount BigNumber Discount amount in cents (tax exclusive).
productId String Manufacturer’s product identifier (eg GTIN/EAN).
restricted Boolean Disallow payment with a “restricted” Asset Type.
classification Object Product Classification.

Product Classification

Mandatory Fields

Field Type Description
type String The classification type (see below).
code String The classification code.
name String The classification title.

Optional Fields

Field Type Description
props Map The product classification properties (see below).

Classification Types

Currently only “GS1” is supported. See GS1 Global Product Classification. When “GS1” is used as the product classification type then the product code should be the GPC product brick identifier.

Classification Properties

Classification properties allow optional additional product characterizing attrubutes to be supplied. In the case of GS1 product classifications this corresponds to the GPC brick attributes.

The Paid By provides a summary of the transactions after the Payment Request was paid.

Mandatory Fields

Field Type Description
assetTotals Array The sum of paid amounts Asset Totals for each transacted asset type.

Asset Total

Mandatory Fields

Field Type Description
type String The asset type used for the payment.
description String A human readable description of the asset type used.
settlementDate Timestamp The estimated date that the merchant can expect settlement of funds.
total Monetary The total monetary value of the asset type used to pay a Payment Request

Payment Activity EXPERIMENTAL

A Payment Activity records a transaction that has happened on a Payment Request. Payment Activities are created when a Payment Request has been created, paid, refunded, cancelled, or expired.

Mandatory Fields

Field Type Description
type String See Activity Types below.
value Monetary The value of the payment activity. Must be positive.
paymentRequestId String The Payment Request’s id.
merchantId String The Payment Request’s Merchant id.
merchantConfigId String The Payment Request’s Merchant Config id.
merchantAccountId String The Payment Request’s Merchant Account id.
merchantName String The Payment Request’s Merchant name.
createdAt Timestamp When the activity was created.
createdBy CRN The identity that created the activity.
paymentRequestCreatedBy CRN The identity that created the Payment Request.
activityNumber BigNumber Unique sequential number for the activity.
shortCode String A shorter id that can be used for up to two years.

Optional Fields

Field Type Description
assetType String The Asset Type for the “payment” or “refund” activity.
external Boolean The payment activity is recording a transaction that occurred outside the Centrapay system.
cancellationReason String The reason that the Payment Request was cancelled. See Cancellation Reasons for possible values.
conditionId Number The id of a condition if the activity was for a condition being accepted or declined.
idempotencyKey String Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness.
confirmationIdempotencyKey String Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation.

Activity Types

Name Description
request Payment Request was created.
payment Payment Request was paid.
refund Funds were returned to the shopper.
cancellation Payment Request was cancelled by the merchant or the shopper.
expiry Payment Request wasn’t paid before time out.
accept-condition A Payment Condition was accepted.
decline-condition A Payment Condition was declined.
confirmation Funds on a Pre Auth have been drawn down on.
release Pre Auth has been finalised and any remaining funds from Authorization have been returned.

Cancellation Reasons

Reason Description
CANCELLED_BY_MERCHANT The merchant cancelled the payment request by calling the cancel or void endpoint.
CANCELLED_BY_PATRON The patron cancelled the transaction.
PATRON_CODE_INVALID The patron code on the payment request was invalid.
INSUFFICIENT_ASSET_VALUE 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.
PAYMENT_FAILED The payment request failed for an unknown reason.
PATRON_CODE_EXPIRED The patron code on the payment request has expired.
DECLINED_BY_PATRON The payment was declined by the patron during approval steps.
DECLINED_BY_MERCHANT The payment was declined by the merchant during approval steps.
PAYMENT_DECLINED The payment parameters were valid but payment was declined because additional payment restrictions were violated. For example, asset not active, asset overdrawn, quota exceeded or line item category restrictions.
PAYMENT_REQUEST_EXPIRED The payment request has expired.
NO_AVAILABLE_PAYMENT_OPTIONS No payment options match the requested payment parameters.

Operations

Create a Payment Request

POST /api/payment-requests

Create a Payment Request 

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "5efbe2fb96c08357bb2b9242",
    "value": {
      "amount": "8991",
      "currency": "NZD"
    }
  }'

Create a Payment Request with redirect url 

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "5efbe2fb96c08357bb2b9242",
    "value": {
      "amount": "8991",
      "currency": "NZD"
    },
    "redirectUrl": "https://example.com/store/checkout?cartId=1234"
  }'

Create a Payment Request with a Barcode 

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "1219210961929460",
    "configId": "5efbe2fb96c08357bb2b9242",
    "value": {
      "amount": "8991",
      "currency": "NZD"
    }
  }'

Create a Pre Auth Payment Request 

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "1219210961929460",
    "configId": "5efbe2fb96c08357bb2b9242",
    "value": {
      "amount": "8991",
      "currency": "NZD"
    },
    "preAuth": true
  }'

Create a Payment Request with purchase order, invoice, and external reference 

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "5efbe2fb96c08357bb2b9242",
    "value": {
      "amount": "8991",
      "currency": "NZD"
    },
    "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
    "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
    "externalRef": "dYTC266s4DFdsgGd909f"
  }'

Create a Payment Request with Line Items 

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "5efbe2fb96c08357bb2b9242",
    "value": {
      "amount": "6190",
      "currency": "NZD"
    },
    "lineItems": [
      {
        "name": "Coffee Grounds",
        "sku": "GH1234",
        "qty": "1",
        "price": "4195",
        "tax": "15.00"
      },
      {
        "name": "Centrapay Cafe Mug",
        "sku": "SB456",
        "qty": "25",
        "price": "1995",
        "tax": "15.00",
        "discount": "199",
        "restricted": true,
        "productId": "19412345123459",
        "classification": {
          "type": "GS1",
          "code": "10001874",
          "name": "CROCKERY",
          "props": {
            "20001479": "30008960"
          }
        }
      }
    ]
  }'

Fields

Field Type Description
configId String The Merchant Config id used to configure the payment options.
value Monetary The canonical value of the payment request. Must be positive.
barcode String Optional The Scanned Code to identify the account to attach the payment request to
expirySeconds String Optional How long the payment request will be payable for. Maximum value: 86400 (24 hours).
lineItems Array Optional Experimental The Line Items being paid for.
purchaseOrderRef String Optional A reference to a purchase order for this payment request.
invoiceRef String Optional A reference to an invoice for this payment request.
externalRef String Optional An external reference to the payment request
redirectUrl String Optional Experimental URL to redirect the user to after they pay or cancel the Payment Request. Must start with one of the allowedRedirectUrls for the Merchant Config.
terminalId String Optional The software or logical id of the payment terminal.
deviceId String Optional The hardware id or serial number of the payment terminal.
operatorId String Optional The POS operator Id.
createdByAccountId String Optional The id of the Centrapay Account creating the Payment Request.
createdByAccountName String Optional The name of the Centrapay Account creating the Payment Request.
conditionsEnabled Boolean Optional Flag to opt into accepting Asset Types which require conditions to be met. If not set, assets which require conditions will not be payment options.
patronNotPresent Boolean Optional Flag to indicate the patron is not physically present. This may affect payment conditions or available Payment Options.
preAuth Boolean Optional Flag to indicate if the Payment Request is a Pre Auth for supported Asset Types. If set barcode must be provided.

Example response payload 

{
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "barcode": "9990001234567895",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Centrapay Café",
  "configId": "5efbe2fb96c08357bb2b9242",
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "value": {
    "currency": "NZD",
    "amount": "6190"
  },
  "paymentOptions": [
    {
      "amount": "6190",
      "assetType": "centrapay.nzd.test"
    },
    {
      "amount": "6190",
      "assetType": "epay.nzd.test",
      "productCodes": [
        "23403"
      ]
    }
  ],
  "lineItems": [
    {
      "name": "Coffee Grounds",
      "sku": "GH1234",
      "qty": "1",
      "price": "4195",
      "tax": "15.00"
    },
    {
      "name": "Centrapay Cafe Mug",
      "sku": "SB456",
      "qty": "25",
      "price": "1995",
      "tax": "15.00",
      "discount": "199"
    }
  ],
  "merchantConditions": [

  ],
  "status": "new",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "liveness": "test",
  "expirySeconds": 120
}

Error Responses

Status Code Description
400 LINE_ITEMS_SUM_CHECK_FAILED The sum value of the line items did not equal the value of the payment request.
403 REDIRECT_URL_INVALID The supplied redirectUrl does not start with one of the allowedRedirectUrls on the Merchant Config.
400 CHECKSUM_FAILED Luhn checksum digit doesn’t pass.
403 PATRON_CODE_INVALID Patron Code doesn’t exist or has expired.
403 NO_AVAILABLE_PAYMENT_OPTIONS No payment options match the requested payment parameters.

Get a Payment Request

GET /api/payment-requests/{paymentRequestId} 

curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
  -H "Authorization: $jwt"

Example response payload 

{
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "barcode": "9990001234567895",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Centrapay Café",
  "configId": "5efbe2fb96c08357bb2b9242",
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "value": {
    "currency": "NZD",
    "amount": "8991"
  },
  "paymentOptions": [
    {
      "amount": "8991",
      "assetType": "centrapay.nzd.test"
    }
  ],
  "lineItems": [
    {
      "name": "Coffee Grounds",
      "sku": "GH1234",
      "qty": "1",
      "price": "4195",
      "tax": "15.00"
    },
    {
      "name": "Centrapay Cafe Mug",
      "sku": "SB456",
      "qty": "25",
      "price": "1995",
      "tax": "15.00",
      "discount": "199"
    }
  ],
  "merchantConditions": [
    {
      "id": "1",
      "name": "photo-id-check",
      "message": "Please check ID",
      "status": "awaiting-merchant"
    }
  ],
  "status": "new",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "liveness": "test",
  "expirySeconds": 120
}

Example response payload paid by multiple asset types 

{
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Centrapay Café",
  "configId": "5efbe2fb96c08357bb2b9242",
  "value": {
    "currency": "NZD",
    "amount": "1000"
  },
  "paymentOptions": [
    {
      "amount": "1000",
      "assetType": "centrapay.nzd.main"
    },
    {
      "amount": "1000",
      "assetType": "cca.coke.main"
    }
  ],
  "merchantConditions": [

  ],
  "status": "paid",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "liveness": "main",
  "expirySeconds": 120,
  "paidBy": {
    "assetTotals": [
      {
        "type": "centrapay.nzd.main",
        "description": "Centrapay NZD",
        "settlementDate": "2021-06-28T04:04:27.426Z",
        "total": {
          "amount": "550",
          "currency": "NZD"
        }
      },
      {
        "type": "cca.coke.main",
        "description": "Coke Token",
        "settlementDate": "2021-06-28T04:04:27.426Z",
        "total": {
          "amount": "450",
          "currency": "NZD"
        }
      }
    ]
  }
}

Example response payload for a Pre Auth Payment Request 

{
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "barcode": 503901342,
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Centrapay Café",
  "configId": "5efbe2fb96c08357bb2b9242",
  "value": {
    "currency": "NZD",
    "amount": "1000"
  },
  "paymentOptions": [
    {
      "amount": "1000",
      "assetType": "farmlands.nzd.main"
    }
  ],
  "merchantConditions": [

  ],
  "status": "new",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "liveness": "main",
  "expirySeconds": 120,
  "preAuth": true,
  "preAuthStatus": "authorized",
  "preAuthExpiresAt": "2021-09-08T04:04:27.426Z"
}

Get a Payment Request by Short Code

Returns the latest Payment Request that matches the given short code.

GET /api/payment-requests/short-code/{shortCode} 

curl https://service.centrapay.com/api/payment-requests/short-code/CP-C7F-ZS5 \
  -H "Authorization: $jwt"

Example response payload with a Payment Request 

{
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "barcode": "9990001234567895",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Centrapay Café",
  "configId": "5efbe2fb96c08357bb2b9242",
  "value": {
    "currency": "NZD",
    "amount": "100"
  },
  "paymentOptions": [
    {
      "amount": "100",
      "assetType": "centrapay.nzd.test"
    }
  ],
  "merchantConditions": [

  ],
  "status": "new",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "liveness": "test",
  "expirySeconds": 120
}

Error Responses

Status Code Description
400 CHECKSUM_FAILED Luhn checksum digit doesn’t pass.

Get a Payment Request linked to a Patron Code

Returns the latest Payment Request with status “new” that has been attached to a Patron Code. The Payment Request may have been created with a reference to any Patron Code owned by the user’s account.

This endpoint should be polled just after a user’s Patron Code has been scanned. This will allow them to find the Payment Request and proceed to pay.

GET /api/me/patron-code-payment-request 

curl https://service.centrapay.com/api/me/patron-code-payment-request \
  -H "Authorization: $jwt"

Example response payload when no new Payment Request found 

{
}

Example response payload with a Payment Request 

{
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "barcode": "9990001234567895",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Centrapay Café",
  "configId": "5efbe2fb96c08357bb2b9242",
  "value": {
    "currency": "NZD",
    "amount": "100"
  },
  "paymentOptions": [
    {
      "amount": "100",
      "assetType": "centrapay.nzd.test"
    }
  ],
  "merchantConditions": [

  ],
  "status": "new",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "liveness": "test",
  "expirySeconds": 120
}

Pay a Payment Request EXPERIMENTAL

There are two methods of paying a payment request. The first uses Centrapay Assets and requires you to provide the Id and the type of the asset. Alternatively you can provide an external transaction Id and the Centrapay Asset Type for any payments that we support. An example of an external transaction would be a Bitcoin payment.

POST /api/payment-requests/{paymentRequestId}/pay

Pay a Payment Request with a Centrapay asset 

curl -X POST https://service.centrapay.com/api/payment-requests/{paymentRequestId}/pay \
  -H "Authorization: $jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "assetType": "centrapay.nzd.main",
    "assetId": "WRhAxxWpTKb5U7pXyxQjjY"
  }'

Pay a Payment Request using external transaction 

curl -X POST https://service.centrapay.com/api/payment-requests/{paymentRequestId}/pay \
  -H "Authorization: $jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "assetType": "bitcoin.main",
    "transactionId": "VMXMkUttDGTVz4ESv5ND56"
  }'

Example response payload 

{
  "type": "payment",
  "value": {
    "currency": "NZD",
    "amount": "1000"
  },
  "assetType": "centrapay.nzd.main",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-015",
  "merchantName": "Centrapay Café",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5efbe2fb96c08357bb2b9242",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "2"
}

Error Responses

Status Code Description
403 INVALID_ASSET_TYPE Either the merchant is not configured with the provided asset type or the asset type does not exist.
403 REQUEST_EXPIRED Action cannot be completed because the request has expired.
403 REQUEST_PAID Action cannot be completed because the request has been paid.
403 REQUEST_CANCELLED Action cannot be completed because the request has already been cancelled.
403 INACTIVE_ASSET The asset is not spendable. It may have been disabled, expired, or already spent.
403 INVALID_MERCHANT_CONFIG 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_EXCEEDED The payment pay request exceeds the allowed spend quota supplied.
403 INSUFFICIENT_ASSET_VALUE 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_REDEMPTION_DENIED The asset redemption has been unsuccessful due to an error with provided payment parameters, the merchant, or the asset.
403 PAYMENT_DECLINED The payment parameters were valid but payment was declined because additional payment restrictions were violated.

Refund a Payment Request EXPERIMENTAL

POST /api/payment-requests/{paymentRequestId}/refund

Refund a Payment Request 

curl -X POST https://service.centrapay.com/api/payment-requests/{paymentRequestId}/refund \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "amount": "100",
      "currency": "NZD"
    },
    "externalRef": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a"
  }'

Refund a Payment Request with Line Items 

curl -X POST https://service.centrapay.com/api/payment-requests/{paymentRequestId}/refund \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "amount": "6190",
      "currency": "NZD"
    },
    "externalRef": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
    "lineItems": [
      {
        "name": "Coffee Grounds",
        "sku": "GH1234",
        "qty": "1",
        "price": "4195",
        "tax": "15.00"
      },
      {
        "name": "Centrapay Cafe Mug",
        "sku": "SB456",
        "qty": "25",
        "price": "1995",
        "tax": "15.00",
        "discount": "199",
        "restricted": true,
        "productId": "19412345123459",
        "classification": {
          "type": "GS1",
          "code": "10001874",
          "name": "CROCKERY",
          "props": {
            "20001479": "30008960"
          }
        }
      }
    ]
  }'

Refund a Pre Auth Payment Request with Confirmations 

curl -X POST https://service.centrapay.com/api/payment-requests/{paymentRequestId}/refund \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmationIdempotencyKey": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
    "value": {
      "amount": "6190",
      "currency": "NZD"
    },
    "lineItems": [
      {
        "name": "Coffee Grounds",
        "sku": "GH1234",
        "qty": "1",
        "price": "4195",
        "tax": "15.00"
      },
      {
        "name": "Centrapay Cafe Mug",
        "sku": "SB456",
        "qty": "25",
        "price": "1995",
        "tax": "15.00",
        "discount": "199",
        "restricted": true,
        "productId": "19412345123459",
        "classification": {
          "type": "GS1",
          "code": "10001874",
          "name": "CROCKERY",
          "props": {
            "20001479": "30008960"
          }
        }
      }
    ]
  }'

Example response payload 

{
  "type": "refund",
  "value": {
    "currency": "NZD",
    "amount": "100"
  },
  "assetType": "centrapay.nzd.main",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-015",
  "merchantName": "Centrapay Café",
  "merchantId": "5ee0c486308f590260d9a07f",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "createdAt": "2021-06-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "3"
}

Error Responses

Status Code Description
403 NOT_PAID The Payment Request has not been paid.
403 ALREADY_REFUNDED The Payment Request already been refunded. If you want to perfom additional refunds then an externalRef is required.
403 INVALID_AMOUNT The refund requested is greater than the refundable amount.
403 REPEAT_REFERENCE A refund has already been requested with the same external reference. Refunding the payment request 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 PARTIAL_REFUNDS_NOT_ALLOWED The Asset does not support partial refunds.
403 INACTIVE_ASSET The Asset is not refundable. It may have been disabled, expired, or already refunded.
403 REFUND_NOT_SUPPORTED The Asset type does not support refunds.
403 REFUND_WINDOW_EXCEEDED The time since the payment exceeds the window of time a payment request can be refunded in.
400 LINE_ITEMS_SUM_CHECK_FAILED The sum value of the line items did not equal the value of the refund.
403 PRE_AUTH_PENDING The Pre Auth Payment Request has yet to be authorized.
403 CONFIRMATION_NOT_FOUND The confirmationIdempotencyKey does not match a Confirmation on the Payment Request.

Void a Payment Request EXPERIMENTAL

Voiding a payment request will cancel the request and trigger any refunds if necessary.

POST /api/payment-requests/{paymentRequestId}/void 

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/void \
  -H "X-Api-Key: $api_key"

Example response payload when payment request is unpaid 

{
  "type": "cancellation",
  "cancellationReason": "CANCELLED_BY_MERCHANT",
  "value": {
    "currency": "NZD",
    "amount": "1000"
  },
  "assetType": "centrapay.nzd.main",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-032",
  "merchantName": "Centrapay Café",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5efbe2fb96c08357bb2b9242",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "2"
}

Example response payload when payment request is paid 

{
  "type": "refund",
  "value": {
    "currency": "NZD",
    "amount": "1000"
  },
  "assetType": "centrapay.nzd.main",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-032",
  "merchantName": "Centrapay Café",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5efbe2fb96c08357bb2b9242",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "3"
}

Error Responses

Status Code Description
403 VOID_WINDOW_EXCEEDED The void window is closed 24 hours after the Payment Request createdAt. After the void window has closed if the Payment Request is paid, use Refund endpoint to reverse the payment.
403 ALREADY_REFUNDED The Payment Request has already been refunded.
403 REPEAT_REFERENCE A refund has already been requested with the same external reference. Refunding the payment request 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 INACTIVE_ASSET The Asset is not refundable. It may have been disabled, expired, or already refunded.
403 REFUND_NOT_SUPPORTED The Asset type does not support refunds.
403 REQUEST_EXPIRED The Payment Request has expired.
403 PRE_AUTH_ALREADY_CONFIRMED The Pre Auth Payment Request already has confirmations. Use Refund endpoint to reverse the transaction.

Release funds held for a Pre Auth Payment Request EXPERIMENTAL

When you call release on a Pre Auth Payment Request any remaining funds that were being held for the authorization are returned to the asset, and a release Payment Activity is returned. If the authorization never completed, the Payment Request will instead be cancelled, and a cancellation Payment Activity will be returned.

POST /api/payment-requests/{paymentRequestId}/release 

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/release \
  -H "X-Api-Key: $api_key"

Example response payload when a Pre Auth is released 

{
  "type": "release",
  "value": {
    "currency": "NZD",
    "amount": "100"
  },
  "assetType": "centrapay.nzd.main",
  "preAuth": true,
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-015",
  "merchantName": "Centrapay Café",
  "merchantId": "5ee0c486308f590260d9a07f",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "createdAt": "2021-06-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "3"
}

Example response payload when a Pre Auth is cancelled 

{
  "type": "cancellation",
  "cancellationReason": "CANCELLED_BY_MERCHANT",
  "value": {
    "currency": "NZD",
    "amount": "1000"
  },
  "preAuth": true,
  "assetType": "centrapay.nzd.main",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-032",
  "merchantName": "Centrapay Café",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5efbe2fb96c08357bb2b9242",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "2"
}

Error Responses

Status Code Description
403 INVALID_PAYMENT_REQUEST_TYPE The Payment Request is not related to a Pre Auth.
403 PRE_AUTH_RELEASED preAuthExpiresAt has passed.

Make a confirmation against a Pre Auth Payment Request EXPERIMENTAL

An idempotencyKey is a identifier from your system used for guaranteeing at least once delivery of your request. If our endpoint does not respond you must retry until you get back a 200 or 403. If we recive 2 requests with the same idempotencyKey we won’t process the second and return the first response.

POST /api/payment-requests/{paymentRequestId}/confirm

Confirm Pre Auth Payment Request 

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/confirm \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "amount": "6190",
      "currency": "NZD"
    },
    "idempotencyKey": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
    "invoiceRef": "2022-08-03T16:56:50-06:00",
    "lineItems": [
      {
        "name": "Coffee Grounds",
        "sku": "GH1234",
        "qty": "1",
        "price": "4195",
        "tax": "15.00"
      },
      {
        "name": "Centrapay Cafe Mug",
        "sku": "SB456",
        "qty": "25",
        "price": "1995",
        "tax": "15.00",
        "discount": "199",
        "restricted": true,
        "productId": "19412345123459",
        "classification": {
          "type": "GS1",
          "code": "10001874",
          "name": "CROCKERY",
          "props": {
            "20001479": "30008960"
          }
        }
      }
    ]
  }'

Example response payload when a Pre Auth is confirmed 

{
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5",
  "value": {
    "amount": "6190",
    "currency": "NZD"
  },
  "preAuth": true,
  "type": "confirmation",
  "idempotencyKey": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "lineItems": [
    {
      "name": "Coffee Grounds",
      "sku": "GH1234",
      "qty": "1",
      "price": "4195",
      "tax": "15.00"
    },
    {
      "name": "Centrapay Cafe Mug",
      "sku": "SB456",
      "qty": "25",
      "price": "1995",
      "tax": "15.00",
      "discount": "199"
    }
  ],
  "invoiceRef": "2022-08-03T16:56:50-06:00",
  "createdByAccountId": "Jaim1Cu1Q55uooxSens6yk",
  "createdByAccountName": "Bob's Burgers Intergration"
}

Error Responses

Status Code Description
403 INVALID_PAYMENT_REQUEST_TYPE The Payment Request is not related to a Pre Auth.
403 PRE_AUTH_RELEASED The Payment Request has been released or Pre Auth has expired. Remaining funds have been returned to the Patron.
403 PRE_AUTH_PENDING The Payment Request has not been authorized.
403 REQUEST_CANCELLED The Payment Request has been cancelled.
403 INVALID_AMOUNT The confirmation is greater then the remaining funds on the authroization.
403 IDEMPOTENT_OPERATION_FAILED There has already been a confirmation against the Payment Request with the same idempotencyKey but different content.

List Payment Activities for a Merchant EXPERIMENTAL

List payment activities for a merchant. Results are paginated and ordered by descending activity created date.

GET /api/payment-activities 

curl -G https://service.centrapay.com/api/payment-activities \
  -H "X-Api-Key: $api_key" \
  -d merchantId=5ee0c486308f590260d9a07f \
  -d pageKey=PaymentRequest#E9eXsErwA444qFDoZt5iLA|Activity#000000000000001|614161c4c4d3020073bd4ce8|2021-09-15T03:00:21.156Z

Required Fields

Field Type Description
merchantId String The id of the Merchant the Payment Request is on behalf of.

Optional Fields

Field Type Description
pageKey String Used to retrieve the next page of items.

Example response payload 

{
  "nextPageKey": "PaymentRequest#E9eXsErwA444qFDoZt5iLA|Activity#000000000000001|614161c4c4d3020073bd4ce8|2021-09-15T03:00:21.156Z",
  "items": [
    {
      "type": "refund",
      "value": {
        "currency": "NZD",
        "amount": "600"
      },
      "assetType": "centrapay.nzd.main",
      "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
      "shortCode": "CP-C7F-ZS5-032",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-06-12T01:17:00.000Z",
      "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "3"
    },
    {
      "type": "payment",
      "value": {
        "currency": "NZD",
        "amount": "6190"
      },
      "assetType": "centrapay.nzd.main",
      "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
      "shortCode": "CP-C7F-ZS5-027",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-06-12T01:16:00.000Z",
      "createdBy": "crn::user:da75ad90-9a5b-4df0-8374-f48b3a8fbfcc",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "2"
    },
    {
      "type": "request",
      "value": {
        "currency": "NZD",
        "amount": "6190"
      },
      "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
      "shortCode": "CP-C7F-ZS5-015",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-06-12T01:15:46.000Z",
      "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "1"
    }
  ]
}

List Payment Activities for a Payment Request EXPERIMENTAL

List payment activities for a payment request. Results are ordered by descending activity created date.

GET /api/payment-requests/{paymentRequestId}/activities 

curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/activities \
  -H "Authorization: $jwt"

Example response payload 

{
  "items": [
    {
      "type": "refund",
      "value": {
        "currency": "NZD",
        "amount": "600"
      },
      "assetType": "centrapay.nzd.main",
      "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
      "shortCode": "CP-C7F-ZS5-032",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-06-12T01:17:00.000Z",
      "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "3"
    },
    {
      "type": "payment",
      "value": {
        "currency": "NZD",
        "amount": "6190"
      },
      "assetType": "centrapay.nzd.main",
      "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
      "shortCode": "CP-C7F-ZS5-027",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-06-12T01:16:00.000Z",
      "createdBy": "crn::user:da75ad90-9a5b-4df0-8374-f48b3a8fbfcc",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "2"
    },
    {
      "type": "request",
      "value": {
        "currency": "NZD",
        "amount": "6190"
      },
      "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
      "shortCode": "CP-C7F-ZS5-015",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-06-12T01:15:46.000Z",
      "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "1"
    }
  ]
}

Accept Payment Condition for a Payment Request EXPERIMENTAL

Accept a Payment Condition listed in merchantConditions with status awaiting-merchant. Returns a Payment Activity.

POST /api/payment-requests/{paymentRequestId}/conditions/{conditionId}/accept 

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/accept \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "type": "accept-condition",
  "value": {
    "currency": "NZD",
    "amount": 100
  },
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "conditionId": "1",
  "createdAt": "2022-05-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "2",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantId": "5ee0c486308f590260d9a07f",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "merchantName": "Centrapay Café"
}

Error Responses

Status Code Description
403 PATRON_NOT_AUTHORIZED The Payment Condition is awaiting-merchant, therefore the patron is not authorized to accept the condition.
403 MERCHANT_NOT_AUTHORIZED The Payment Condition is awaiting-patron, therefore the merchant is not authorized to accept the condition.
403 CONDITION_ALREADY_SET The Payment Condition has already been accepted or declined.

Decline Payment Condition for a Payment Request EXPERIMENTAL

Decline a Payment Condition listed in merchantConditions with status awaiting-merchant. Returns a Payment Activity.

POST /api/payment-requests/{paymentRequestId}/conditions/{conditionId}/decline 

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/decline \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "type": "decline-condition",
  "value": {
    "currency": "NZD",
    "amount": 100
  },
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "conditionId": "1",
  "createdAt": "2022-05-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "activityNumber": "2",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantId": "5ee0c486308f590260d9a07f",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "merchantName": "Centrapay Café"
}

Error Responses

Status Code Description
403 PATRON_NOT_AUTHORIZED The Payment Condition is awaiting-merchant, therefore the patron is not authorized to decline the condition.
403 MERCHANT_NOT_AUTHORIZED The Payment Condition is awaiting-patron, therefore the merchant is not authorized to decline the condition.
403 CONDITION_ALREADY_SET The Payment Condition has already been accepted or declined.