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.

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 Centrapay merchant id.
merchantName
string
The name of the merchant.
configId
string
The Merchant Config 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
string
When the Payment Request was created.
updatedAt
string
When the Payment Request was updated.
expiresAt
string
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 the Payment Request is attached to.
barcode
string
Scanned Code used to create the Payment Request. Required when the Quick Pay payment flow is used.
barcodeType
string
Indicates the provider of a barcode, e.g. ticketek.
collectionId
string
The identifier of the Token Collection.
expirySeconds
integer
The expiry seconds used to configure the Payment Request expiry.
lineItems
array
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.
redirectCancelUrl
stringexperimental
URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the Merchant Config.
redirectPaidUrl
stringexperimental
URL to redirect the user to after they pay 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 if the request is a Pre Auth for supported Asset Types.
preAuthExpiresAt
string
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 that the Merchant belongs to. See Tax Number.
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. Required when partialAllowed is true.
connectionId
stringexperimental
The identifier of the Connection associated with the payment request.
connectionStatus
stringexperimental
The status of the Connection associated with the payment request.
paymentLinkId
stringexperimental
The identifier of the Payment Link.

Payment Option Model

Attributes

assetType
string
An Asset Type 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.*.
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.

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 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 with matching collection id.

Payment Condition Model

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.

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.

Either price or unitPrice must be supplied. If price is supplied it is used as-is; if only unitPrice is supplied, price is computed as unitPrice * qty. When both are supplied, price takes priority and is not validated against unitPrice * qty.

Attributes

name
stringrequired
The product description.
sku
string
The product (stock keeping unit) code. Required for Token redemptions.
qty
bignumberrequired
The product quantity (eg. item count, weight, volume etc).
unitMeasure
string
A free-text label describing the unit of qty (eg. kg, L, seat). Display only, maximum 20 characters.
price
bignumberrequired
The total price in cents for the line item (eg. price = product price * qty - discounts + tax). Either price or unitPrice is required; if both are supplied, price takes priority.
unitPrice
string
The price of a single unit of qty, in cents. Used to compute price when price is not supplied.
tax
bignumber
Tax rate (percentage).
discount
bignumber
Discount amount in cents (tax exclusive).
metadata
object
A set of up to 20 key-value string pairs for storing additional structured information about the line item. Keys may be up to 40 characters; values up to 500 characters.
productId
string
Manufacturer's product identifier (eg GTIN/EAN).
restricted
boolean
Disallow payment with a “restricted” Asset Type.
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.

Paid By Model

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

Attributes

assetTotals
array
The Asset Totals for each transacted Asset Type.

Asset Totals

The Asset Totals provides a sum of every transaction for each Asset Type

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
array
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

id
string
The unique identifier of the Payment Activity.
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 Centrapay merchant id.
merchantConfigId
string
The Payment Request's Merchant Config id.
merchantAccountId
string
The Payment Request's Merchant Account id.
merchantName
string
The name of the merchant.
createdAt
string
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
integer
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.
paidBy
object
Shows the Paid By when a Payment Request is paid.
strategy
object
Details about the specifics for a refund. See Strategy Model

Strategy Model

Attributes

refunds
array
The list of refunds that will be processed.
refunds.assetId
string
The ID of the Asset that will be refunded.
refunds.assetType
string
The Asset Type of the Asset that will be refunded.
refunds.completedPaymentId
string
ID of a Payment Activity of type: payment that the refund is against.
refunds.amount
string
The amount that will be refunded back to the Asset.
refunds.collectionId
string
The ID of the Token Collection if applicable.

Payment Activity Types

Name	Description
request	Payment Request was created.
preAuthRequest	Payment Request was created with the `preAuth` flag set to "true".
paid	Payment Request was paid.
payment	A payment was made towards the Payment Request.
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.
authorization	A Pre Auth Payment Request was approved and confirmations can be made against it.
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.
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.
INACTIVE_ASSET	The asset used to pay the Payment Request is inactive.

Create a Payment Request

This endpoint allows you to create a Payment Request for a given Merchant Config and value.

Attributes

configId
stringrequired
The Merchant Config 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 used to create the Payment Request. Required when the Quick Pay payment flow is used.
barcodeType
string
Indicates the provider of a barcode, e.g. ticketek.
collectionId
string
The identifier of the Token Collection.
expirySeconds
integer
The expiry seconds used to configure the Payment Request expiry.
lineItems
array
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.
redirectCancelUrl
stringexperimental
URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the Merchant Config.
redirectPaidUrl
stringexperimental
URL to redirect the user to after they pay 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.
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.
preAuth
boolean
Flag to indicate if the request is a Pre Auth for supported Asset Types.
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.
connectionId
stringexperimental
The identifier of the Connection associated with the payment request.
paymentLinkId
stringexperimental
The identifier of the Payment Link.

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.
BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
REDIRECT_URL_INVALID
403
One or more of the supplied redirect urls do not start with one of the allowedRedirectUrls on the Merchant Config.
PATRON_CODE_INVALID
403
Patron Code 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.
CONNECTION_NOT_FOUND
403
The connection does not exist.
CONNECTION_MERCHANT_MISMATCH
403
The connection is not for the same merchant as the payment request.
CONNECTION_CREATED_BY_MISMATCH
403
The connection was not created by the same caller as the payment request.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X POST https://service.centrapay.com/api/payment-requests \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "configId": "mc_5efbe2fb96c08357bb2b9242",
  "expirySeconds": 120,
  "value": {
    "amount": "10000",
    "currency": "NZD"
  },
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "connectionId": "cn_9asd9k19",
  "paymentLinkId": "pl_5srt998b"
}'

{
  "id": "VYowvZmuw3hbp1va9xqWx7",
  "shortCode": "CP-X4V-6N",
  "url": "https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7",
  "merchantId": "5efbe17d96c083633e2b9241",
  "merchantName": "NZD Test Merchant",
  "configId": "mc_5efbe2fb96c08357bb2b9242",
  "value": {
    "amount": "10000",
    "currency": "NZD"
  },
  "status": "new",
  "liveness": "test",
  "expirySeconds": 120,
  "createdAt": "2023-10-23T22:56:46.145Z",
  "updatedAt": "2023-10-23T22:56:46.145Z",
  "expiresAt": "2023-10-23T22:58:46.145Z",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "connectionId": "cn_9asd9k19",
  "connectionStatus": "active",
  "paymentLinkId": "pl_5srt998b"
}

Get a Payment Request

This endpoint allows you to retrieve a Payment Request. |

Attributes

paymentRequestId
stringrequired
The Payment Request id.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X GET https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
-H 'x-api-key: <TOKEN>'

{
  "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"
    }
  ],
  "paidBy": {
    "assetTotals": [
      {
        "type": "centrapay.nzd.test",
        "description": "Centrapay NZD Test",
        "settlementDate": "2026-02-11T00:31:31.661Z",
        "total": {
          "amount": "1000",
          "currency": "NZD"
        },
        "payerAccountId": "Bn8Wawd21Y2yoGb2KuSdK2"
      }
    ]
  },
  "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,
  "connectionId": "cn_9asd9k19",
  "connectionStatus": "active"
}

Get a Payment Request by Short Code

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

Attributes

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

Errors

CHECKSUM_FAILED
400
Luhn checksum digit doesn't pass.
BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X GET https://service.centrapay.com/api/payment-requests/short-code/CP-C7F-ZS5 \
-H 'x-api-key: <TOKEN>'

{
  "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,
  "connectionId": "cn_9asd9k19",
  "connectionStatus": "active"
}

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

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X GET https://service.centrapay.com/api/me/patron-code-payment-request \
-H 'x-api-key: <TOKEN>'

{
  "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,
  "connectionId": "cn_9asd9k19",
  "connectionStatus": "active"
}

Get a Payment Request by Connection Id

This endpoint returns the latest Payment Request that is associated with the provided Connection. The caller of the endpoint must be the account that authorized the connection.

Attributes

connectionId
stringrequired
The identifier of the Connection associated with the payment request.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X GET https://service.centrapay.com/api/connections/cn_9asd9k19/latest-payment-request \
-H 'x-api-key: <TOKEN>'

{
  "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,
  "connectionId": "cn_9asd9k19",
  "connectionStatus": "authorized"
}

List Payment Requests by External Reference

This endpoint returns a list of Payment Requests that match the given external reference. Results are paginated.

Attributes

externalRef
stringrequired
An external reference to the Payment Request.
merchantAccountId
stringrequired
The Account of the merchant that the Payment Request was created for.
pageKey
string
Used to retrieve the next page of items. Note that the pageKey value, if provided, needs to be URL-encoded.
paginationLimit
string
Maximum number of Payment Requests to return.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X GET 'https://service.centrapay.com/api/payment-requests/external-ref/e8df06e2-13a5-48b4-b670-3fd6d815fe0a?merchantAccountId=1mdj7bj95gjo92r0ux6wfy69gj3h77' \
-H 'x-api-key: <TOKEN>'

{
  "items": [
    {
      "id": "MhocUmpxxmgdHjr7DgKoKw",
      "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
      "merchantName": "Centrapay Café",
      "value": {
        "currency": "NZD",
        "amount": "8991"
      },
      "createdAt": "2021-06-08T04:04:27.426Z",
      "expiresAt": "2021-06-08T04:06:27.426Z",
      "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"
                }
              ]
            }
          ]
        }
      ],
      "status": "new",
      "liveness": "test",
      "connectionId": "cn_9asd9k19",
      "connectionStatus": "active"
    }
  ],
  "pageKey": "12312312"
}

Get Payment Request Summary

This endpoint allows you to retrieve the summary of a Payment Request while the status is new.

Attributes

paymentRequestId
stringrequired
The Payment Request id.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X GET https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/summary \
-H 'x-api-key: <TOKEN>'

{
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Centrapay Café",
  "value": {
    "currency": "NZD",
    "amount": "8991"
  },
  "createdAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "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"
            }
          ]
        }
      ]
    }
  ],
  "partialAllowed": true,
  "basketAmount": "8991",
  "remainingAmount": "8991",
  "status": "new",
  "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"
    }
  ],
  "liveness": "test"
}

Pay a Payment Request

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

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

Attributes

paymentRequestId
stringrequired
The Payment Request id.
assetType
stringrequired
An Asset Type reference.
idempotencyKey
stringrequired
A unique identifier that prevents duplicate processing of the same request. See idempotency.
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 are partial-payment and multi-asset-payment.
amount
bignumber
The value required to pay using the canonical units for the Asset Type.
externalPaymentRef
string
An external reference to the payment. Required when assetType is farmlands.nzd.*.
lineItems
array
The Line Items associated with this payment attempt. This field is only allowed for centrapay.token.* payments. If omitted for centrapay.token.* payments, the highest-value valid line item from the payment request will be used by default.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
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.
PAYMENT_UNCONFIRMED
403
Confirmation of payment success or failure was not received from the provider within the expected time.
REMAINING_AMOUNT_EXCEEDED
403
The payment amount exceeds the remaining amount on the Payment Request.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/pay \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "idempotencyKey": "b62-11ec-9072-3e22fb52e878",
  "assetType": "centrapay.nzd.main",
  "assetId": "WRhAxxWpTKb5U7pXyxQjjY",
  "amount": "200",
  "mode": "partial-payment",
  "externalPaymentRef": "62e4b0d7-551b-4b93-8b62-28265b4457d1"
}'

{
  "type": "payment",
  "value": {
    "currency": "NZD",
    "amount": "1000"
  },
  "idempotencyKey": "8b62-11ec-9072-3e22fb52e878",
  "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",
  "id": "94a564c9a66d4893b7edf8ccafe3c5fb",
  "externalPaymentRef": "62e4b0d7-551b-4b93-8b62-28265b4457d1"
}

Refund a Payment Request

This endpoint allows you to initiate a refund of a Payment Request. The refund will be completed asynchronously.

Attributes

paymentRequestId
stringrequired
The Payment Request id.
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
array
The Line Items being refunded.
merchantConfigId
string
The Merchant Config 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.
BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
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.
REFUND_DECLINED
403
The refund parameters were valid but refund was declined because additional business rules were violated.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

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": "3600",
    "currency": "NZD"
  },
  "externalRef": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    }
  ]
}'

{
  "type": "refund",
  "value": {
    "currency": "NZD",
    "amount": "3600"
  },
  "assetType": "centrapay.nzd.main",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-015",
  "merchantName": "Centrapay Café",
  "merchantId": "5ee0c486308f590260d9a07f",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "mc_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",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    }
  ]
}

Void a Payment Request

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

Attributes

paymentRequestId
stringrequired
The Payment Request id.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
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.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/void \
-H 'x-api-key: <TOKEN>'

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

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.

Attributes

paymentRequestId
stringrequired
The Payment Request id.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
INVALID_PAYMENT_REQUEST_TYPE
403
The Payment Request is not related to a Pre Auth.
PRE_AUTH_RELEASED
403
preAuthExpiresAt has passed.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/release \
-H 'x-api-key: <TOKEN>'

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

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

paymentRequestId
stringrequired
The Payment Request id.
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
arrayrequired
The Line Items being confirmed.
value
monetary
The canonical value of the confirmation. Must be less than 100000000 and positive.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
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.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

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

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

List Payment Activities for a Merchant

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

Attributes

merchantId
stringrequired
The id of the Merchant the Payment Request is on behalf of.
pageKey
stringrequired
Used to retrieve the next page of items. Note that the pageKey value, if provided, needs to be URL-encoded.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

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>'

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

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

Attributes

paymentRequestId
stringrequired
The Payment Request id.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X GET https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/activities \
-H 'x-api-key: <TOKEN>'

{
  "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 a Payment Condition

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

Attributes

paymentRequestId
stringrequired
The Payment Request id.
conditionId
stringrequired
An enumerated identifier for the Payment Condition.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
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.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/accept \
-H 'x-api-key: <TOKEN>'

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

Decline a Payment Condition

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

Attributes

paymentRequestId
stringrequired
The Payment Request id.
conditionId
stringrequired
An enumerated identifier for the Payment Condition.

Errors

BAD REQUEST
400
The request is malformed or missing required fields.
UNAUTHORIZED
401
API key or JWT is missing, expired or invalid. See Auth.
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.
FORBIDDEN
403
Resource missing, permission denied, or business rule violated.
NOT FOUND
404
The requested resource does not exist or you do not have access.
RATE LIMIT EXCEEDED
429
Centrapay API rate limits have been exceeded. See Rate Limits.
SERVER ERROR
500
Something went wrong on our end. Retrying should solve the issue.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/decline \
-H 'x-api-key: <TOKEN>'

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

Payment Request Model

Attributes

id

shortCode

url

value

paymentOptions

merchantId

merchantName

configId

status

liveness

createdAt

updatedAt

expiresAt

merchantConditions

remainingAmount

patronCodeId

barcode

barcodeType

collectionId

expirySeconds

lineItems

purchaseOrderRef

invoiceRef

redirectCancelUrl

redirectPaidUrl

externalRef

terminalId

deviceId

operatorId

createdByAccountId

createdByAccountName

conditionsEnabled

patronNotPresent

cancellationReason

preAuth

preAuthExpiresAt

preAuthStatus

taxNumber

partialAllowed

paidBy

basketAmount

connectionId

connectionStatus

paymentLinkId

Payment Option Model

Attributes

assetType

amount

bitcoinAddress

acceptedCollections

Accepted Collections

Attributes

id

lineItems

Payment Condition Model

Attributes

id

name

message

status

Line Item Model

Attributes

name

sku

qty

unitMeasure

price

unitPrice

tax

discount

metadata

productId

restricted

classification

Product Classification

Attributes

type

code