Go to home page
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  API ).

Payment Request Model

Attributes

  • 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 less than 100000000 and positive.

  • paymentOptions

    array

    The Payment Options, indicating valid asset for payment.

  • merchantId

    string

    The id of the Merchant  API  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  API  id used to configure the payment options.

  • status

    string

    Valid values: 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.

  • remainingAmount

    bignumber

    The amount of the Payment Request which has not been paid for.

  • patronCodeId

    string

    The id of a Patron Code  API  the Payment Request is attached to.

  • barcode

    string

    Scanned Code  API  used to create the Payment Request.

  • barcodeType

    string

    Indicates the provider of a barcode, e.g. ticketek.

  • collectionId

    string

    The identifier of the Token Collection  API .

  • expirySeconds

    number

    The expiry seconds used to configure the Payment Request expiry.

  • lineItems

    arrayexperimental

    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. Must be less than or equal to 128 characters.

  • redirectUrl

    stringexperimental

    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  API .

  • 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  API  creating the Payment Request.

  • createdByAccountName

    string

    Name of the Centrapay Account  API  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  API .

  • 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

    object

    The value-added tax configuration for the Business  API  that the Merchant  API  belongs to. See Tax Number  API .

  • partialAllowed

    boolean

    Flag to indicate that the Payment Request can be paid for partially.

  • paidBy

    object

    Shows the Paid By when a Payment Request is paid for with multiple Assets.

  • basketAmount

    bignumber

    The total amount of the transaction including non Centrapay payment methods.

Payment Option Model

Attributes

  • assetType

    string

    An Asset Type  API  reference.

  • amount

    bignumber

    The value required to pay using the canonical units for the Asset Type.

  • bitcoinAddress

    string

    ⭐️ Address to send Bitcoin, when the assetType is bitcoin.*.

  • productCodes

    array

    Supported product codes for the Payment Request, when the assetType is epay.nzd.*.

  • acceptedCollections

    array

    Accepted Collections for the Payment Request, when the “assetType” is centrapay.token.*.

⭐️ 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.

Accepted Collections

If a Payment Request contains a centrapay.token.* Payment Option, an array of Accepted Collections will be present inside the centrapay.token Payment Option. The Accepted Collections returned can be used to determine if a Centrapay Token  API  can be used to pay a Payment Request, and the Line Items able to be purchased using the Token.

Attributes

  • id

    string

    The id of a collection that the Merchant accepts for the given Payment Request.

  • lineItems

    array

    The Line Items that can be purchased by a Centrapay Token  API  with matching collection id.

Payment Condition Model

Some Asset Types  API  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.

Attributes

  • 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 Model

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.

Attributes

  • 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).

  • 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  API .

  • classification

    object

    Product Classification.

Product Classification

Attributes

  • type

    string

    The classification type. 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.

  • code

    string

    The classification code.

  • name

    string

    The classification title.

  • props

    object

    The product 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.

Attributes

  • assetTotals

    array

    The sum of paid amounts Asset Totals for each transacted Asset Type.

Asset Totals

Attributes

  • 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.

  • lineItems

    arrayexperimental

    The Line Items paid for by the Asset Type.

Payment Activity Model

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.

Attributes

  • type

    string

    The Payment Activity Type.

  • value

    monetary

    The value of the Payment Activity. Must be less than 100000000 and positive.

  • paymentRequestId

    string

    The Payment Request’s id.

  • merchantId

    string

    The Payment Request’s Merchant  API  id.

  • merchantConfigId

    string

    The Payment Request’s Merchant Config  API  id.

  • merchantAccountId

    string

    The Payment Request’s Merchant Account  API  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.

  • assetType

    string

    The Asset Type for the payment or refund activity.

  • external

    boolean

    true if 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.

  • preAuth

    boolean

    true if the related Payment Request is a Pre Auth.

Payment Activity Types

NameDescription
requestPayment Request was created.
preAuthRequestPayment Request was created with the preAuth flag set to “true”.
paidPayment Request was paid.
paymentA payment was made towards the Payment Request.
refundFunds were returned to the shopper.
cancellationPayment Request was cancelled by the merchant or the shopper.
expiryPayment Request wasn’t paid before time out.
accept-conditionA Payment Condition was accepted.
decline-conditionA Payment Condition was declined.
authorizationA Pre Auth Payment Request was approved and confirmations can be made against it.
confirmationFunds on a Pre Auth have been drawn down on.
releasePre Auth has been finalised and any remaining funds from Authorization have been returned.

Cancellation Reasons

ReasonDescription
CANCELLED_BY_MERCHANTThe merchant cancelled the Payment Request by calling the cancel or void endpoint.
CANCELLED_BY_PATRONThe patron cancelled the transaction.
PATRON_CODE_INVALIDThe patron code on the Payment Request was invalid.
PAYMENT_FAILEDThe Payment Request failed for an unknown reason.
PATRON_CODE_EXPIREDThe patron code on the Payment Request has expired.
DECLINED_BY_PATRONThe payment was declined by the patron during approval steps.
DECLINED_BY_MERCHANTThe payment was declined by the merchant during approval steps.
PAYMENT_DECLINEDThe 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_EXPIREDThe Payment Request has expired.
NO_AVAILABLE_PAYMENT_OPTIONSNo payment options match the requested payment parameters.
INACTIVE_ASSETThe asset used to pay the Payment Request is inactive.
POST/api/payment-requests

Create a Payment Request

This endpoint allows you to create a Payment Request.

Attributes

  • configId

    stringrequired

    The Merchant Config  API  id used to configure the payment options.

  • value

    monetaryrequired

    The canonical value of the Payment Request. Must be less than 100000000 and positive.

  • barcode

    string

    Scanned Code  API  used to create the Payment Request. Required when preAuth is true.

  • barcodeType

    string

    Indicates the provider of a barcode, e.g. ticketek.

  • collectionId

    string

    The identifier of the Token Collection  API .

  • expirySeconds

    number

    The expiry seconds used to configure the Payment Request expiry.

  • lineItems

    arrayexperimental

    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. Must be less than or equal to 128 characters.

  • redirectUrl

    stringexperimental

    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  API .

  • 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.

  • createdByAccountName

    string

    Name of the Centrapay Account  API  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.

  • preAuth

    boolean

    Flag to indicate the if the request is a Pre Auth for supported Asset Types  API .

  • partialAllowed

    boolean

    Flag to indicate that the Payment Request can be paid for partially.

  • basketAmount

    bignumber

    The total amount of the transaction including non Centrapay payment methods. Required when partialAllowed is true.

Errors

  • LINE_ITEMS_SUM_CHECK_FAILED

    400

    The sum value of the line items did not equal the value of the Payment Request.

  • CHECKSUM_FAILED

    400

    Luhn checksum digit doesn’t pass.

  • REDIRECT_URL_INVALID

    403

    The supplied redirectUrl does not start with one of the allowedRedirectUrls on the Merchant Config  API .

  • PATRON_CODE_INVALID

    403

    Patron Code  API  doesn’t exist or has expired.

  • NO_AVAILABLE_PAYMENT_OPTIONS

    403

    No payment options match the requested payment parameters.

  • TOKEN_COLLECTION_NOT_FOUND

    403

    The token collection does not exist.

Request
POST/api/payment-requests
curl -X POST \
 https://service.centrapay.com/api/payment-requests \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "configId": "5efbe2fb96c08357bb2b9242",
 "expirySeconds": "120",
 "value": {
  "amount": "1",
  "currency": "NZD"
 }
}
'
Response
{
  "id": "VYowvZmuw3hbp1va9xqWx7",
  "shortCode": "CP-X4V-6N",
  "url": "https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7",
  "merchantId": "5efbe17d96c083633e2b9241",
  "merchantName": "NZD Test Merchant",
  "configId": "5efbe2fb96c08357bb2b9242",
  "value": {
    "amount": "1",
    "currency": "NZD"
  },
  "paymentOptions": [
    {
      "assetType": "centrapay.nzd.test",
      "amount": "1"
    },
    {
      "assetType": "cca.coke.test",
      "amount": "1"
    },
    {
      "assetType": "farmlands.nzd.test",
      "amount": "1"
    },
    {
      "assetType": "quartz.nzd.test",
      "amount": "1"
    },
    {
      "assetType": "uplinkapi.test",
      "amount": "1"
    },
    {
      "assetType": "epay.nzd.test",
      "amount": "1",
      "productCodes": [
        "23403"
      ]
    }
  ],
  "status": "new",
  "createdAt": "2023-10-23T22:56:46.145Z",
  "updatedAt": "2023-10-23T22:56:46.145Z",
  "expiresAt": "2023-10-23T22:58:46.145Z",
  "liveness": "test",
  "expirySeconds": 120,
  "merchantConditions": [],
  "createdByAccountId": "BtCjTpNwFcbuJQUP1c4qXp",
  "createdByAccountName": "Smoke Test Merchant Prod",
  "taxNumber": {
    "value": "123-456-789",
    "type": "nz-gst"
  },
  "remainingAmount": "1"
}
GET/api/payment-requests/{paymentRequestId}

Get a Payment Request

This endpoint allows you to retrieve a Payment Request.

Request
GET/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw
curl -X GET \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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"
    },
    {
      "amount": "6190",
      "assetType": "centrapay.token.test",
      "acceptedCollections": [
        {
          "id": "QWNB6jurnBczmvXDVfRuMK",
          "lineItems": [
            {
              "name": "Coffee Grounds",
              "sku": "GH1234",
              "qty": "1",
              "price": "4195",
              "tax": "15.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"
    }
  ],
  "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
}
GET/api/payment-requests/short-code/{shortCode}

Get a Payment Request by Short Code

This endpoint returns the latest Payment Request that matches the given short code.

Errors

  • CHECKSUM_FAILED

    400

    Luhn checksum digit doesn’t pass.

Request
GET/api/payment-requests/short-code/CP-C7F-ZS5
curl -X GET \
 https://service.centrapay.com/api/payment-requests/short-code/CP-C7F-ZS5 \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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
}
GET/api/me/patron-code-payment-request

Get a Payment Request linked to a Patron Code

This endpoint returns the latest Payment Request with status new that has been attached to a Patron Code  API . 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.

Request
GET/api/me/patron-code-payment-request
curl -X GET \
 https://service.centrapay.com/api/me/patron-code-payment-request \
 -H 'authorization: <TOKEN>'
Response
{
  "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
}
POST/api/payment-requests/{paymentRequestId}/pay

Pay a Payment Request

To pay a Payment Request you must supply the name of the Asset Type  API  and one of assetId, transactionId or authorization.

  • Use assetId if the Asset Type  API  is managed by Centrapay.
  • Use transactionId to verify an external transaction such as a Bitcoin payment.
  • Use authorization to authorize an external transaction.

Attributes

  • assetType

    stringrequired

    An Asset Type  API  reference.

  • assetId

    string

    The id of the Asset being used to make payment.

  • transactionId

    string

    Used to verify an external transaction eg Bitcoin.

  • authorization

    string

    Used to authorize an external transaction.

  • mode

    string

    The mode of payment. Valid values: parital-payment.

  • amount

    string

    The value required to pay using the canonical units for the Asset Type.

Errors

  • INVALID_ASSET_TYPE

    403

    Either the merchant is not configured with the provided asset type or the asset type does not exist.

  • 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.

  • 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.

  • PAYMENT_DECLINED

    403

    The payment parameters were valid but payment was declined because additional payment restrictions were violated.

Request
POST/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/pay
curl -X POST \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/pay \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "assetType": "centrapay.nzd.main",
 "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
 "amount": "200",
 "mode": "partial-payment"
}
'
Response
{
  "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",
  "mode": "partial-payment"
}
POST/api/payment-requests/{paymentRequestId}/refund

Refund a Payment Request

This endpoint allows you to refund a Payment Request.

Attributes

  • value

    monetaryrequired

    The canonical value of the Payment Request. Must be less than 100000000 and positive.

  • externalRef

    stringrequired

    An external reference to the refund.

  • invoiceRef

    string

    A reference to an invoice for the refund. Must be less than or equal to 128 characters.

  • confirmationIdempotencyKey

    string

    Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation.

  • lineItems

    arrayexperimental

    The Line Items being refunded.

  • merchantConfigId

    string

    The Merchant Config  API  id of the refunding merchant when refunding a farmlands.nzd.* payment.

Errors

  • LINE_ITEMS_SUM_CHECK_FAILED

    400

    The sum value of the line items did not equal the value of the refund.

  • NOT_PAID

    403

    The Payment Request has not been paid.

  • ALREADY_REFUNDED

    403

    The Payment Request already been refunded. If you want to perfom additional refunds then an externalRef is required.

  • INVALID_AMOUNT

    403

    The refund requested is greater than the refundable amount.

  • REPEAT_REFERENCE

    403

    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.

  • 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 payment request can be refunded in.

  • PRE_AUTH_PENDING

    403

    The Pre Auth Payment Request has yet to be authorized.

  • CONFIRMATION_NOT_FOUND

    403

    The confirmationIdempotencyKey does not match a Confirmation on the Payment Request.

Request
POST/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/refund
curl -X POST \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/refund \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "value": {
  "amount": "100",
  "currency": "NZD"
 },
 "externalRef": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a"
}
'
Response
{
  "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",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423"
}
POST/api/payment-requests/{paymentRequestId}/void

Void a Payment Request

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

Errors

  • VOID_WINDOW_EXCEEDED

    403

    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.

  • ALREADY_REFUNDED

    403

    The Payment Request already been refunded.

  • REPEAT_REFERENCE

    403

    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.

  • 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.

  • REQUEST_EXPIRED

    403

    The Payment Request has expired.

  • PRE_AUTH_ALREADY_CONFIRMED

    403

    The Pre Auth Payment Request already has confirmations. Use Refund endpoint to reverse the transaction.

Request
POST/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/void
curl -X POST \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/void \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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"
}
POST/api/payment-requests/{paymentRequestId}/release

Release Pre Auth funds

This endpoint allows you to release funds held for a Pre Auth Payment Request.

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.

Errors

  • INVALID_PAYMENT_REQUEST_TYPE

    403

    The Payment Request is not related to a Pre Auth.

  • PRE_AUTH_RELEASED

    403

    preAuthExpiresAt has passed.

Request
POST/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/release
curl -X POST \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/release \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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"
}
POST/api/payment-requests/{paymentRequestId}/confirm

Confirm Pre Auth Payment Request

This endpoint allows you to make a confirmation against a Pre Auth Payment Request.

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.

Attributes

  • idempotencyKey

    stringrequired

    This is an identifier from your system to enforce uniqueness.

  • invoiceRef

    stringrequired

    A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters.

  • lineItems

    arrayrequiredexperimental

    The Line Items being confirmed.

  • value

    monetary

    The canonical value of the confirmation. Must be less than 100000000 and positive.

Errors

  • INVALID_PAYMENT_REQUEST_TYPE

    403

    The Payment Request is not related to a Pre Auth.

  • PRE_AUTH_RELEASED

    403

    The Payment Request has been released or Pre Auth has expired. Remaining funds have been returned to the Patron.

  • PRE_AUTH_PENDING

    403

    The Payment Request has not been authorized.

  • REQUEST_CANCELLED

    403

    The Payment Request has been cancelled.

  • INVALID_AMOUNT

    403

    The confirmation is greater then the remaining funds on the authroization.

  • IDEMPOTENT_OPERATION_FAILED

    403

    There has already been a confirmation against the Payment Request with the same idempotencyKey but different content.

Request
POST/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/confirm
curl -X POST \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/confirm \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -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"
    }
   }
  }
 ]
}
'
Response
{
  "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"
}
GET/api/payment-activities

List Payment Activities for a Merchant

This endpoint allows you to list Payment Activities for a Merchant. Results are paginated  API  and ordered by descending activity created date.

Attributes

  • merchantId

    stringrequired

    The id of the Merchant  API  the Payment Request is on behalf of.

  • pageKey

    stringrequired

    Used to retrieve the next page of items. Note: The pageKey value, if provided, needs to be URL-encoded.

Request
GET/api/payment-activities
curl -X GET \
 'https://service.centrapay.com/api/payment-activities?merchantId=5ee0c486308f590260d9a07f&pageKey=PaymentRequest%23E9eXsErwA444qFDoZt5iLA%7CActivity%23000000000000001%7C614161c4c4d3020073bd4ce8%7C2021-09-15T03%3A00%3A21.156Z' \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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"
    },
    {
      "type": "Authorization",
      "value": {
        "currency": "NZD",
        "amount": "100"
      },
      "paymentRequestId": "5zXMDueDJRNNyP3UeWBgSA",
      "shortCode": "CP-W4R-01J",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-05-12T01:15:46.000Z",
      "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "2",
      "preAuth": true
    },
    {
      "type": "preAuthRequest",
      "value": {
        "currency": "NZD",
        "amount": "100"
      },
      "paymentRequestId": "5zXMDueDJRNNyP3UeWBgSA",
      "shortCode": "CP-W4R-01J",
      "merchantName": "Centrapay Café",
      "merchantId": "5ee0c486308f590260d9a07f",
      "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
      "merchantConfigId": "5ee168e8597be5002af7b454",
      "createdAt": "2021-05-12T01:15:46.000Z",
      "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
      "activityNumber": "1",
      "preAuth": true
    }
  ]
}
GET/api/payment-requests/{paymentRequestId}/activities

List Payment Activities for a Payment Request

This endpoint allows you to list Payment Activities for a Payment Request. Results are ordered by descending activity created date.

Request
GET/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/activities
curl -X GET \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/activities \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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"
    }
  ]
}
POST/api/payment-requests/{paymentRequestId}/conditions/{conditionId}/accept

Accept a Payment Condition

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

Errors

  • PATRON_NOT_AUTHORIZED

    403

    The Payment Condition is awaiting-merchant, therefore the patron is not authorized to accept the condition.

  • MERCHANT_NOT_AUTHORIZED

    403

    The Payment Condition is awaiting-patron, therefore the merchant is not authorized to accept the condition.

  • CONDITION_ALREADY_SET

    403

    The Payment Condition has already been accepted or declined.

Request
POST/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/accept
curl -X POST \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/accept \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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é"
}
POST/api/payment-requests/{paymentRequestId}/conditions/{conditionId}/decline

Decline a Payment Condition

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

Errors

  • PATRON_NOT_AUTHORIZED

    403

    The Payment Condition is awaiting-merchant, therefore the patron is not authorized to decline the condition.

  • MERCHANT_NOT_AUTHORIZED

    403

    The Payment Condition is awaiting-patron, therefore the merchant is not authorized to decline the condition.

  • CONDITION_ALREADY_SET

    403

    The Payment Condition has already been accepted or declined.

Request
POST/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/decline
curl -X POST \
 https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/decline \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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é"
}