openapi: 3.2.0 info: title: Centrapay Payment Requests API version: 1.0.0 x-page: title: Payment Requests description: Payment request models and related endpoints nav: path: Payment Requests order: 1 intro: '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](/guides/payment-flows/) 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. ' models: - payment-request - payment-option - accepted-collections - payment-condition - line-item - product-classification - paid-by - asset-totals - payment-activity - strategy extras: - title: Payment Activity Types depth: 3 body: '| Name | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------- | | request | [Payment Request](#payment-request-model) was created. | | preAuthRequest | [Payment Request](#payment-request-model) was created with the `preAuth` flag set to "true". | | paid | [Payment Request](#payment-request-model) was paid. | | payment | A payment was made towards the [Payment Request](#payment-request-model). | | refund | Funds were returned to the shopper. | | cancellation | [Payment Request](#payment-request-model) was cancelled by the merchant or the shopper. | | expiry | [Payment Request](#payment-request-model) wasn''t paid before time out. | | accept-condition | A [Payment Condition](#payment-condition-model) was accepted. | | decline-condition | A [Payment Condition](#payment-condition-model) was declined. | | authorization | A Pre Auth [Payment Request](#payment-request-model) 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. | ' - title: Cancellation Reasons depth: 2 body: '| 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. | ' servers: - url: https://service.centrapay.com description: Centrapay production API (host taken from the curl examples on https://docs.centrapay.com/api/payment-requests; the source spec declares no servers[]) tags: - name: payment-requests paths: /api/payment-requests: post: x-method: POST x-path: /api/payment-requests operationId: createPaymentRequest summary: Create a Payment Request description: This endpoint allows you to create a Payment Request for a given Merchant Config and value. tags: - payment-requests requestBody: required: true content: application/json: schema: type: object required: - configId - value properties: configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). examples: default: value: 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 responses: '200': description: Payment Request created content: application/json: schema: x-title: Payment Request Model type: object properties: id: type: string example: VYowvZmuw3hbp1va9xqWx7 description: The Payment Request id. shortCode: type: string example: CP-X4V-6N description: A shorter id that can be used to identify the Payment Request for up to two years. url: type: string example: https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7 description: The URL for a Centrapay webpage that allows the user to pay the Payment Request. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentOptions: type: array description: The [Payment Options](#payment-option-model), indicating valid asset for payment. items: x-title: Payment Option Model x-outro: '⭐️ 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](#pay-a-payment-request). ' type: object properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. bitcoinAddress: type: string description: ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. acceptedCollections: type: array description: '[Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`.' items: x-title: Accepted Collections x-intro: '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/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. ' type: object properties: id: type: string description: The id of a collection that the Merchant accepts for the given Payment Request. lineItems: type: array description: The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. status: type: string enum: - new - paid - cancelled - expired description: 'Valid values: `new`, `paid`, `cancelled`, or `expired`.' liveness: type: string enum: - test - main description: Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. createdAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was created. updatedAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was updated. expiresAt: type: string format: date-time example: '2023-10-23T22:58:46.145Z' description: When the Payment Request expires. merchantConditions: type: array description: A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). items: x-title: Payment Condition Model x-intro: 'Some [Asset Types](/api/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](#create-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](#accept-a-payment-condition) or [declined](#decline-a-payment-condition). If a condition is declined, the Payment Request will be cancelled. ' type: object properties: id: x-type: bignumber type: string description: An enumerated identifier for the Payment Condition. name: type: string description: The name of the condition. message: type: string description: The human-readable description of the condition. status: type: string description: The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. remainingAmount: x-type: bignumber type: string description: The amount of the Payment Request which has not been paid for. patronCodeId: type: string description: The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountId: type: string description: Id of the [Centrapay Account](/api/accounts) creating the Payment Request. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). preAuthExpiresAt: type: string format: date-time description: Pre Auth completions and releases will be accepted until this time. preAuthStatus: type: string description: Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. taxNumber: type: object description: The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. connectionStatus: type: string x-experimental: true description: The status of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). x-examples: PaymentRequestBody: value: 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 PaymentRequestResponse: value: 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 examples: default: value: 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 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: LINE_ITEMS_SUM_CHECK_FAILED: description: The sum value of the line items did not equal the value of the Payment Request. value: message: LINE_ITEMS_SUM_CHECK_FAILED CHECKSUM_FAILED: description: Luhn checksum digit doesn't pass. value: message: CHECKSUM_FAILED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: REDIRECT_URL_INVALID: description: One or more of the supplied redirect urls do not start with one of the `allowedRedirectUrls` on the [Merchant Config](/api/merchant-configs). value: message: REDIRECT_URL_INVALID PATRON_CODE_INVALID: description: '[Patron Code](/api/patron-codes) doesn''t exist or has expired.' value: message: PATRON_CODE_INVALID NO_AVAILABLE_PAYMENT_OPTIONS: description: No payment options match the requested payment parameters. value: message: NO_AVAILABLE_PAYMENT_OPTIONS TOKEN_COLLECTION_NOT_FOUND: description: The token collection does not exist. value: message: TOKEN_COLLECTION_NOT_FOUND CONNECTION_NOT_FOUND: description: The connection does not exist. value: message: CONNECTION_NOT_FOUND CONNECTION_MERCHANT_MISMATCH: description: The connection is not for the same merchant as the payment request. value: message: CONNECTION_MERCHANT_MISMATCH CONNECTION_CREATED_BY_MISMATCH: description: The connection was not created by the same caller as the payment request. value: message: CONNECTION_CREATED_BY_MISMATCH /api/payment-requests/{paymentRequestId}: get: x-method: GET x-path: /api/payment-requests/{paymentRequestId} operationId: getPaymentRequest summary: Get a Payment Request description: This endpoint allows you to retrieve a Payment Request. tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. responses: '200': description: Payment Request retrieved content: application/json: schema: x-title: Payment Request Model type: object properties: id: type: string example: VYowvZmuw3hbp1va9xqWx7 description: The Payment Request id. shortCode: type: string example: CP-X4V-6N description: A shorter id that can be used to identify the Payment Request for up to two years. url: type: string example: https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7 description: The URL for a Centrapay webpage that allows the user to pay the Payment Request. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentOptions: type: array description: The [Payment Options](#payment-option-model), indicating valid asset for payment. items: x-title: Payment Option Model x-outro: '⭐️ 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](#pay-a-payment-request). ' type: object properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. bitcoinAddress: type: string description: ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. acceptedCollections: type: array description: '[Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`.' items: x-title: Accepted Collections x-intro: '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/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. ' type: object properties: id: type: string description: The id of a collection that the Merchant accepts for the given Payment Request. lineItems: type: array description: The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. status: type: string enum: - new - paid - cancelled - expired description: 'Valid values: `new`, `paid`, `cancelled`, or `expired`.' liveness: type: string enum: - test - main description: Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. createdAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was created. updatedAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was updated. expiresAt: type: string format: date-time example: '2023-10-23T22:58:46.145Z' description: When the Payment Request expires. merchantConditions: type: array description: A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). items: x-title: Payment Condition Model x-intro: 'Some [Asset Types](/api/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](#create-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](#accept-a-payment-condition) or [declined](#decline-a-payment-condition). If a condition is declined, the Payment Request will be cancelled. ' type: object properties: id: x-type: bignumber type: string description: An enumerated identifier for the Payment Condition. name: type: string description: The name of the condition. message: type: string description: The human-readable description of the condition. status: type: string description: The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. remainingAmount: x-type: bignumber type: string description: The amount of the Payment Request which has not been paid for. patronCodeId: type: string description: The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountId: type: string description: Id of the [Centrapay Account](/api/accounts) creating the Payment Request. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). preAuthExpiresAt: type: string format: date-time description: Pre Auth completions and releases will be accepted until this time. preAuthStatus: type: string description: Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. taxNumber: type: object description: The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. connectionStatus: type: string x-experimental: true description: The status of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). x-examples: PaymentRequestBody: value: 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 PaymentRequestResponse: value: 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 examples: default: value: 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 /api/payment-requests/short-code/{shortCode}: get: x-method: GET x-path: /api/payment-requests/short-code/{shortCode} operationId: getPaymentRequestByShortCode summary: Get a Payment Request by Short Code description: This endpoint returns the latest Payment Request that matches the given short code. tags: - payment-requests parameters: - name: shortCode in: path required: true schema: type: string example: CP-C7F-ZS5 description: A shorter id that can be used to identify the Payment Request for up to two years. responses: '200': description: Payment Request retrieved content: application/json: schema: x-title: Payment Request Model type: object properties: id: type: string example: VYowvZmuw3hbp1va9xqWx7 description: The Payment Request id. shortCode: type: string example: CP-X4V-6N description: A shorter id that can be used to identify the Payment Request for up to two years. url: type: string example: https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7 description: The URL for a Centrapay webpage that allows the user to pay the Payment Request. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentOptions: type: array description: The [Payment Options](#payment-option-model), indicating valid asset for payment. items: x-title: Payment Option Model x-outro: '⭐️ 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](#pay-a-payment-request). ' type: object properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. bitcoinAddress: type: string description: ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. acceptedCollections: type: array description: '[Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`.' items: x-title: Accepted Collections x-intro: '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/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. ' type: object properties: id: type: string description: The id of a collection that the Merchant accepts for the given Payment Request. lineItems: type: array description: The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. status: type: string enum: - new - paid - cancelled - expired description: 'Valid values: `new`, `paid`, `cancelled`, or `expired`.' liveness: type: string enum: - test - main description: Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. createdAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was created. updatedAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was updated. expiresAt: type: string format: date-time example: '2023-10-23T22:58:46.145Z' description: When the Payment Request expires. merchantConditions: type: array description: A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). items: x-title: Payment Condition Model x-intro: 'Some [Asset Types](/api/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](#create-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](#accept-a-payment-condition) or [declined](#decline-a-payment-condition). If a condition is declined, the Payment Request will be cancelled. ' type: object properties: id: x-type: bignumber type: string description: An enumerated identifier for the Payment Condition. name: type: string description: The name of the condition. message: type: string description: The human-readable description of the condition. status: type: string description: The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. remainingAmount: x-type: bignumber type: string description: The amount of the Payment Request which has not been paid for. patronCodeId: type: string description: The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountId: type: string description: Id of the [Centrapay Account](/api/accounts) creating the Payment Request. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). preAuthExpiresAt: type: string format: date-time description: Pre Auth completions and releases will be accepted until this time. preAuthStatus: type: string description: Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. taxNumber: type: object description: The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. connectionStatus: type: string x-experimental: true description: The status of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). x-examples: PaymentRequestBody: value: 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 PaymentRequestResponse: value: 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 examples: default: value: 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 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: CHECKSUM_FAILED: description: Luhn checksum digit doesn't pass. value: message: CHECKSUM_FAILED /api/me/patron-code-payment-request: get: x-method: GET x-path: /api/me/patron-code-payment-request operationId: getPaymentRequestByPatronCode summary: Get a Payment Request linked to a Patron Code description: '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.' tags: - payment-requests responses: '200': description: Payment Request retrieved content: application/json: schema: x-title: Payment Request Model type: object properties: id: type: string example: VYowvZmuw3hbp1va9xqWx7 description: The Payment Request id. shortCode: type: string example: CP-X4V-6N description: A shorter id that can be used to identify the Payment Request for up to two years. url: type: string example: https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7 description: The URL for a Centrapay webpage that allows the user to pay the Payment Request. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentOptions: type: array description: The [Payment Options](#payment-option-model), indicating valid asset for payment. items: x-title: Payment Option Model x-outro: '⭐️ 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](#pay-a-payment-request). ' type: object properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. bitcoinAddress: type: string description: ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. acceptedCollections: type: array description: '[Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`.' items: x-title: Accepted Collections x-intro: '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/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. ' type: object properties: id: type: string description: The id of a collection that the Merchant accepts for the given Payment Request. lineItems: type: array description: The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. status: type: string enum: - new - paid - cancelled - expired description: 'Valid values: `new`, `paid`, `cancelled`, or `expired`.' liveness: type: string enum: - test - main description: Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. createdAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was created. updatedAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was updated. expiresAt: type: string format: date-time example: '2023-10-23T22:58:46.145Z' description: When the Payment Request expires. merchantConditions: type: array description: A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). items: x-title: Payment Condition Model x-intro: 'Some [Asset Types](/api/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](#create-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](#accept-a-payment-condition) or [declined](#decline-a-payment-condition). If a condition is declined, the Payment Request will be cancelled. ' type: object properties: id: x-type: bignumber type: string description: An enumerated identifier for the Payment Condition. name: type: string description: The name of the condition. message: type: string description: The human-readable description of the condition. status: type: string description: The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. remainingAmount: x-type: bignumber type: string description: The amount of the Payment Request which has not been paid for. patronCodeId: type: string description: The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountId: type: string description: Id of the [Centrapay Account](/api/accounts) creating the Payment Request. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). preAuthExpiresAt: type: string format: date-time description: Pre Auth completions and releases will be accepted until this time. preAuthStatus: type: string description: Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. taxNumber: type: object description: The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. connectionStatus: type: string x-experimental: true description: The status of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). x-examples: PaymentRequestBody: value: 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 PaymentRequestResponse: value: 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 examples: default: value: 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 /api/connections/{connectionId}/latest-payment-request: get: x-method: GET x-path: /api/connections/{connectionId}/latest-payment-request operationId: getPaymentRequestByConnectionId summary: Get a Payment Request by Connection Id description: '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.' tags: - payment-requests parameters: - name: connectionId in: path required: true schema: type: string example: cn_9asd9k19 description: The identifier of the [Connection](/api/connections) associated with the payment request. responses: '200': description: Payment Request retrieved content: application/json: schema: x-title: Payment Request Model type: object properties: id: type: string example: VYowvZmuw3hbp1va9xqWx7 description: The Payment Request id. shortCode: type: string example: CP-X4V-6N description: A shorter id that can be used to identify the Payment Request for up to two years. url: type: string example: https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7 description: The URL for a Centrapay webpage that allows the user to pay the Payment Request. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentOptions: type: array description: The [Payment Options](#payment-option-model), indicating valid asset for payment. items: x-title: Payment Option Model x-outro: '⭐️ 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](#pay-a-payment-request). ' type: object properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. bitcoinAddress: type: string description: ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. acceptedCollections: type: array description: '[Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`.' items: x-title: Accepted Collections x-intro: '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/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. ' type: object properties: id: type: string description: The id of a collection that the Merchant accepts for the given Payment Request. lineItems: type: array description: The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. status: type: string enum: - new - paid - cancelled - expired description: 'Valid values: `new`, `paid`, `cancelled`, or `expired`.' liveness: type: string enum: - test - main description: Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. createdAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was created. updatedAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was updated. expiresAt: type: string format: date-time example: '2023-10-23T22:58:46.145Z' description: When the Payment Request expires. merchantConditions: type: array description: A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). items: x-title: Payment Condition Model x-intro: 'Some [Asset Types](/api/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](#create-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](#accept-a-payment-condition) or [declined](#decline-a-payment-condition). If a condition is declined, the Payment Request will be cancelled. ' type: object properties: id: x-type: bignumber type: string description: An enumerated identifier for the Payment Condition. name: type: string description: The name of the condition. message: type: string description: The human-readable description of the condition. status: type: string description: The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. remainingAmount: x-type: bignumber type: string description: The amount of the Payment Request which has not been paid for. patronCodeId: type: string description: The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountId: type: string description: Id of the [Centrapay Account](/api/accounts) creating the Payment Request. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). preAuthExpiresAt: type: string format: date-time description: Pre Auth completions and releases will be accepted until this time. preAuthStatus: type: string description: Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. taxNumber: type: object description: The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. connectionStatus: type: string x-experimental: true description: The status of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). x-examples: PaymentRequestBody: value: 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 PaymentRequestResponse: value: 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 examples: default: value: 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 /api/payment-requests/external-ref/{externalRef}: get: x-method: GET x-path: /api/payment-requests/external-ref/{externalRef} operationId: listPaymentRequestsByExternalRef summary: List Payment Requests by External Reference description: 'This endpoint returns a list of Payment Requests that match the given external reference. Results are paginated.' tags: - payment-requests parameters: - name: externalRef in: path required: true schema: type: string example: e8df06e2-13a5-48b4-b670-3fd6d815fe0a description: An external reference to the Payment Request. - name: merchantAccountId in: query required: true schema: type: string example: 1mdj7bj95gjo92r0ux6wfy69gj3h77 description: The [Account](/api/accounts/) of the merchant that the Payment Request was created for. - name: pageKey in: query required: false schema: type: string description: Used to retrieve the next page of items. Note that the `pageKey` value, if provided, needs to be URL-encoded. - name: paginationLimit in: query required: false schema: type: string description: Maximum number of Payment Requests to return. responses: '200': description: Payment Requests listed content: application/json: schema: type: object properties: items: type: array items: x-title: Payment Request Model type: object properties: id: type: string example: VYowvZmuw3hbp1va9xqWx7 description: The Payment Request id. shortCode: type: string example: CP-X4V-6N description: A shorter id that can be used to identify the Payment Request for up to two years. url: type: string example: https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7 description: The URL for a Centrapay webpage that allows the user to pay the Payment Request. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentOptions: type: array description: The [Payment Options](#payment-option-model), indicating valid asset for payment. items: x-title: Payment Option Model x-outro: '⭐️ 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](#pay-a-payment-request). ' type: object properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. bitcoinAddress: type: string description: ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. acceptedCollections: type: array description: '[Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`.' items: x-title: Accepted Collections x-intro: '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/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. ' type: object properties: id: type: string description: The id of a collection that the Merchant accepts for the given Payment Request. lineItems: type: array description: The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. status: type: string enum: - new - paid - cancelled - expired description: 'Valid values: `new`, `paid`, `cancelled`, or `expired`.' liveness: type: string enum: - test - main description: Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. createdAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was created. updatedAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was updated. expiresAt: type: string format: date-time example: '2023-10-23T22:58:46.145Z' description: When the Payment Request expires. merchantConditions: type: array description: A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). items: x-title: Payment Condition Model x-intro: 'Some [Asset Types](/api/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](#create-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](#accept-a-payment-condition) or [declined](#decline-a-payment-condition). If a condition is declined, the Payment Request will be cancelled. ' type: object properties: id: x-type: bignumber type: string description: An enumerated identifier for the Payment Condition. name: type: string description: The name of the condition. message: type: string description: The human-readable description of the condition. status: type: string description: The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. remainingAmount: x-type: bignumber type: string description: The amount of the Payment Request which has not been paid for. patronCodeId: type: string description: The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountId: type: string description: Id of the [Centrapay Account](/api/accounts) creating the Payment Request. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). preAuthExpiresAt: type: string format: date-time description: Pre Auth completions and releases will be accepted until this time. preAuthStatus: type: string description: Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. taxNumber: type: object description: The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. connectionStatus: type: string x-experimental: true description: The status of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). x-examples: PaymentRequestBody: value: 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 PaymentRequestResponse: value: 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 pageKey: type: string examples: default: value: 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' /api/payment-requests/{paymentRequestId}/summary: get: x-method: GET x-path: /api/payment-requests/{paymentRequestId}/summary operationId: getPaymentRequestSummary summary: Get Payment Request Summary description: This endpoint allows you to retrieve the summary of a Payment Request while the status is `new`. tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. responses: '200': description: Payment Request summary retrieved content: application/json: schema: x-title: Payment Request Model type: object properties: id: type: string example: VYowvZmuw3hbp1va9xqWx7 description: The Payment Request id. shortCode: type: string example: CP-X4V-6N description: A shorter id that can be used to identify the Payment Request for up to two years. url: type: string example: https://app.centrapay.com/pay/VYowvZmuw3hbp1va9xqWx7 description: The URL for a Centrapay webpage that allows the user to pay the Payment Request. value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentOptions: type: array description: The [Payment Options](#payment-option-model), indicating valid asset for payment. items: x-title: Payment Option Model x-outro: '⭐️ 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](#pay-a-payment-request). ' type: object properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. bitcoinAddress: type: string description: ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. acceptedCollections: type: array description: '[Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`.' items: x-title: Accepted Collections x-intro: '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/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. ' type: object properties: id: type: string description: The id of a collection that the Merchant accepts for the given Payment Request. lineItems: type: array description: The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. configId: type: string example: mc_5efbe2fb96c08357bb2b9242 description: The [Merchant Config](/api/merchant-configs) id used to configure the payment options. status: type: string enum: - new - paid - cancelled - expired description: 'Valid values: `new`, `paid`, `cancelled`, or `expired`.' liveness: type: string enum: - test - main description: Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. createdAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was created. updatedAt: type: string format: date-time example: '2023-10-23T22:56:46.145Z' description: When the Payment Request was updated. expiresAt: type: string format: date-time example: '2023-10-23T22:58:46.145Z' description: When the Payment Request expires. merchantConditions: type: array description: A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). items: x-title: Payment Condition Model x-intro: 'Some [Asset Types](/api/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](#create-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](#accept-a-payment-condition) or [declined](#decline-a-payment-condition). If a condition is declined, the Payment Request will be cancelled. ' type: object properties: id: x-type: bignumber type: string description: An enumerated identifier for the Payment Condition. name: type: string description: The name of the condition. message: type: string description: The human-readable description of the condition. status: type: string description: The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. remainingAmount: x-type: bignumber type: string description: The amount of the Payment Request which has not been paid for. patronCodeId: type: string description: The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. barcode: type: string description: '[Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used.' barcodeType: type: string description: Indicates the provider of a barcode, e.g. `ticketek`. collectionId: type: string description: The identifier of the [Token Collection](/api/tokens). expirySeconds: type: integer description: The expiry seconds used to configure the Payment Request expiry. lineItems: type: array description: The [Line Items](#line-item-model) being paid for. example: - 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' items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object purchaseOrderRef: type: string description: A reference to a purchase order for this Payment Request. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. redirectCancelUrl: type: string x-experimental: true description: URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). redirectPaidUrl: type: string x-experimental: true description: URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). externalRef: type: string description: An external reference to the Payment Request. terminalId: type: string description: The software or logical id of the payment terminal. deviceId: type: string description: The hardware id or serial number of the payment terminal. operatorId: type: string description: POS operator Id. createdByAccountId: type: string description: Id of the [Centrapay Account](/api/accounts) creating the Payment Request. createdByAccountName: type: string description: Name of the [Centrapay Account](/api/accounts) creating the Payment Request. conditionsEnabled: type: boolean description: Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). patronNotPresent: type: boolean description: Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. preAuth: type: boolean description: Flag to indicate if the request is a Pre Auth for supported [Asset Types](/api/asset-types). preAuthExpiresAt: type: string format: date-time description: Pre Auth completions and releases will be accepted until this time. preAuthStatus: type: string description: Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. taxNumber: type: object description: The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). partialAllowed: type: boolean description: Flag to indicate that the Payment Request can be paid for partially. paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. basketAmount: x-type: bignumber type: string description: The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. connectionId: type: string example: cn_9asd9k19 x-experimental: true description: The identifier of the [Connection](/api/connections) associated with the payment request. connectionStatus: type: string x-experimental: true description: The status of the [Connection](/api/connections) associated with the payment request. paymentLinkId: type: string example: pl_5srt998b x-experimental: true description: The identifier of the [Payment Link](/api/payment-links). x-examples: PaymentRequestBody: value: 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 PaymentRequestResponse: value: 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 examples: default: value: 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 /api/payment-requests/{paymentRequestId}/pay: post: x-method: POST x-path: /api/payment-requests/{paymentRequestId}/pay operationId: payPaymentRequest summary: Pay a Payment Request description: '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.' tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. requestBody: required: true content: application/json: schema: type: object required: - assetType - idempotencyKey properties: assetType: type: string description: An [Asset Type](/api/asset-types) reference. idempotencyKey: type: string description: A unique identifier that prevents duplicate processing of the same request. See [idempotency](/api/idempotency). assetId: type: string description: The id of the Asset being used to make payment. transactionId: type: string description: Used to verify an external transaction eg Bitcoin. authorization: type: string description: Used to authorize an external transaction. mode: type: string description: The mode of payment. Valid values are `partial-payment` and `multi-asset-payment`. amount: x-type: bignumber type: string description: The value required to pay using the canonical units for the Asset Type. externalPaymentRef: type: string description: An external reference to the payment. Required when `assetType` is `farmlands.nzd.*`. lineItems: type: array description: The [Line Items](#line-item-model) 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. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object examples: default: value: idempotencyKey: b62-11ec-9072-3e22fb52e878 assetType: centrapay.nzd.main assetId: WRhAxxWpTKb5U7pXyxQjjY amount: '200' mode: partial-payment externalPaymentRef: 62e4b0d7-551b-4b93-8b62-28265b4457d1 responses: '200': description: Payment Request paid content: application/json: schema: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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 '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: INVALID_ASSET_TYPE: description: Either the merchant is not configured with the provided asset type or the asset type does not exist. value: message: INVALID_ASSET_TYPE REQUEST_EXPIRED: description: Action cannot be completed because the request has expired. value: message: REQUEST_EXPIRED REQUEST_PAID: description: Action cannot be completed because the request has been paid. value: message: REQUEST_PAID REQUEST_CANCELLED: description: Action cannot be completed because the request has already been cancelled. value: message: REQUEST_CANCELLED INACTIVE_ASSET: description: The asset is not spendable. It may have been disabled, expired, or already spent. value: message: INACTIVE_ASSET INVALID_MERCHANT_CONFIG: description: 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. value: message: INVALID_MERCHANT_CONFIG QUOTA_EXCEEDED: description: The payment pay request exceeds the allowed spend quota supplied. value: message: QUOTA_EXCEEDED INSUFFICIENT_ASSET_VALUE: description: 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. value: message: INSUFFICIENT_ASSET_VALUE ASSET_REDEMPTION_DENIED: description: The asset redemption has been unsuccessful due to an error with provided payment parameters, the Merchant, or the Asset. value: message: ASSET_REDEMPTION_DENIED PAYMENT_DECLINED: description: The payment parameters were valid but payment was declined because additional payment restrictions were violated. value: message: PAYMENT_DECLINED PAYMENT_UNCONFIRMED: description: Confirmation of payment success or failure was not received from the provider within the expected time. value: message: PAYMENT_UNCONFIRMED REMAINING_AMOUNT_EXCEEDED: description: The payment amount exceeds the remaining amount on the Payment Request. value: message: REMAINING_AMOUNT_EXCEEDED /api/payment-requests/{paymentRequestId}/refund: post: x-method: POST x-path: /api/payment-requests/{paymentRequestId}/refund operationId: refundPaymentRequest summary: Refund a Payment Request description: This endpoint allows you to initiate a refund of a Payment Request. The refund will be completed asynchronously. tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. requestBody: required: true content: application/json: schema: type: object required: - value - externalRef properties: value: x-type: monetary type: object description: The canonical value of the Payment Request. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string externalRef: type: string description: An external reference to the refund. invoiceRef: type: string description: A reference to an invoice for the refund. Must be less than or equal to 128 characters. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. lineItems: type: array description: The [Line Items](#line-item-model) being refunded. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object merchantConfigId: type: string description: The [Merchant Config](/api/merchant-configs) id of the refunding merchant when refunding a `farmlands.nzd.*` payment. examples: default: value: 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' responses: '200': description: Payment Request refund initiated content: application/json: schema: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: LINE_ITEMS_SUM_CHECK_FAILED: description: The sum value of the line items did not equal the value of the refund. value: message: LINE_ITEMS_SUM_CHECK_FAILED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: NOT_PAID: description: The Payment Request has not been paid. value: message: NOT_PAID ALREADY_REFUNDED: description: The Payment Request already been refunded. If you want to perfom additional refunds then an `externalRef` is required. value: message: ALREADY_REFUNDED INVALID_AMOUNT: description: The refund requested is greater than the refundable amount. value: message: INVALID_AMOUNT REPEAT_REFERENCE: description: 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. value: message: REPEAT_REFERENCE PARTIAL_REFUNDS_NOT_ALLOWED: description: The Asset does not support partial refunds. value: message: PARTIAL_REFUNDS_NOT_ALLOWED INACTIVE_ASSET: description: The Asset is not refundable. It may have been disabled, expired, or already refunded. value: message: INACTIVE_ASSET REFUND_NOT_SUPPORTED: description: The Asset type does not support refunds. value: message: REFUND_NOT_SUPPORTED REFUND_WINDOW_EXCEEDED: description: The time since the payment exceeds the window of time a payment request can be refunded in. value: message: REFUND_WINDOW_EXCEEDED PRE_AUTH_PENDING: description: The Pre Auth Payment Request has yet to be authorized. value: message: PRE_AUTH_PENDING CONFIRMATION_NOT_FOUND: description: The confirmationIdempotencyKey does not match a Confirmation on the Payment Request. value: message: CONFIRMATION_NOT_FOUND REFUND_DECLINED: description: The refund parameters were valid but refund was declined because additional business rules were violated. value: message: REFUND_DECLINED /api/payment-requests/{paymentRequestId}/void: post: x-method: POST x-path: /api/payment-requests/{paymentRequestId}/void operationId: voidPaymentRequest summary: Void a Payment Request description: Voiding a payment request will cancel the request and trigger any refunds if necessary. tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. responses: '200': description: Payment Request voided content: application/json: schema: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: VOID_WINDOW_EXCEEDED: description: 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. value: message: VOID_WINDOW_EXCEEDED ALREADY_REFUNDED: description: The Payment Request already been refunded. value: message: ALREADY_REFUNDED REPEAT_REFERENCE: description: 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. value: message: REPEAT_REFERENCE INACTIVE_ASSET: description: The Asset is not refundable. It may have been disabled, expired, or already refunded. value: message: INACTIVE_ASSET REFUND_NOT_SUPPORTED: description: The Asset type does not support refunds. value: message: REFUND_NOT_SUPPORTED REQUEST_EXPIRED: description: The Payment Request has expired. value: message: REQUEST_EXPIRED PRE_AUTH_ALREADY_CONFIRMED: description: The Pre Auth Payment Request already has confirmations. Use Refund endpoint to reverse the transaction. value: message: PRE_AUTH_ALREADY_CONFIRMED /api/payment-requests/{paymentRequestId}/release: post: x-method: POST x-path: /api/payment-requests/{paymentRequestId}/release operationId: releasePaymentRequest summary: Release Pre Auth funds description: '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.' tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. responses: '200': description: Pre Auth funds released content: application/json: schema: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: INVALID_PAYMENT_REQUEST_TYPE: description: The Payment Request is not related to a Pre Auth. value: message: INVALID_PAYMENT_REQUEST_TYPE PRE_AUTH_RELEASED: description: '`preAuthExpiresAt` has passed.' value: message: PRE_AUTH_RELEASED /api/payment-requests/{paymentRequestId}/confirm: post: x-method: POST x-path: /api/payment-requests/{paymentRequestId}/confirm operationId: confirmPaymentRequest summary: Confirm Pre Auth Payment Request description: '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.' tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. requestBody: required: true content: application/json: schema: type: object required: - idempotencyKey - invoiceRef - lineItems properties: idempotencyKey: type: string description: This is an identifier from your system to enforce uniqueness. invoiceRef: type: string description: A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. lineItems: type: array description: The [Line Items](#line-item-model) being confirmed. items: x-title: Line Item Model x-intro: '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`. ' type: object required: - name - qty - price properties: name: type: string example: Hard Hat description: The product description. sku: type: string example: GH1234 description: The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. qty: x-type: bignumber type: string example: '1' description: The product quantity (eg. item count, weight, volume etc). unitMeasure: type: string example: kg description: A free-text label describing the unit of `qty` (eg. kg, L, seat). Display only, maximum 20 characters. price: x-type: bignumber type: string example: '4000' description: 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: type: string example: '4000' description: The price of a single unit of `qty`, in cents. Used to compute `price` when `price` is not supplied. tax: x-type: bignumber type: string example: '15' description: Tax rate (percentage). discount: x-type: bignumber type: string example: '400' description: Discount amount in cents (tax exclusive). metadata: type: object additionalProperties: type: string example: color: red description: 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: type: string description: Manufacturer's product identifier (eg GTIN/EAN). restricted: type: boolean description: Disallow payment with a “restricted” [Asset Type](/api/asset-types). classification: type: object description: '[Product Classification](#product-classification).' properties: type: type: string code: type: string name: type: string props: type: object value: x-type: monetary type: object description: The canonical value of the confirmation. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string examples: default: value: 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' responses: '200': description: Pre Auth Payment Request confirmed content: application/json: schema: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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 '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: INVALID_PAYMENT_REQUEST_TYPE: description: The Payment Request is not related to a Pre Auth. value: message: INVALID_PAYMENT_REQUEST_TYPE PRE_AUTH_RELEASED: description: The Payment Request has been released or Pre Auth has expired. Remaining funds have been returned to the Patron. value: message: PRE_AUTH_RELEASED PRE_AUTH_PENDING: description: The Payment Request has not been authorized. value: message: PRE_AUTH_PENDING REQUEST_CANCELLED: description: The Payment Request has been cancelled. value: message: REQUEST_CANCELLED INVALID_AMOUNT: description: The confirmation is greater then the remaining funds on the authroization. value: message: INVALID_AMOUNT IDEMPOTENT_OPERATION_FAILED: description: There has already been a confirmation against the Payment Request with the same idempotencyKey but different content. value: message: IDEMPOTENT_OPERATION_FAILED /api/payment-activities: get: x-method: GET x-path: /api/payment-activities operationId: listPaymentActivities summary: List Payment Activities for a Merchant description: 'This endpoint allows you to list Payment Activities for a Merchant. Results are paginated and ordered by descending activity created date.' tags: - payment-requests parameters: - name: merchantId in: query required: true schema: type: string example: 5ee0c486308f590260d9a07f description: The id of the [Merchant](/api/merchants/) the Payment Request is on behalf of. - name: pageKey in: query required: true schema: type: string example: PaymentRequest#E9eXsErwA444qFDoZt5iLA|Activity#000000000000001|614161c4c4d3020073bd4ce8|2021-09-15T03:00:21.156Z description: Used to retrieve the next page of items. Note that the `pageKey` value, if provided, needs to be URL-encoded. responses: '200': description: Payment Activities listed content: application/json: schema: type: object properties: items: type: array items: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) nextPageKey: type: string examples: default: value: 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' /api/payment-requests/{paymentRequestId}/activities: get: x-method: GET x-path: /api/payment-requests/{paymentRequestId}/activities operationId: listPaymentRequestActivities summary: List Payment Activities for a Payment Request description: 'This endpoint allows you to list Payment Activities for a Payment Request. Results are ordered by descending activity created date.' tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. responses: '200': description: Payment Activities listed content: application/json: schema: type: object properties: items: type: array items: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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' /api/payment-requests/{paymentRequestId}/conditions/{conditionId}/accept: post: x-method: POST x-path: /api/payment-requests/{paymentRequestId}/conditions/{conditionId}/accept operationId: acceptPaymentCondition summary: Accept a Payment Condition description: 'Accept a Payment Condition listed in `merchantConditions` with status `awaiting-merchant`. Returns a Payment Activity.' tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. - name: conditionId in: path required: true schema: type: string example: '1' description: An enumerated identifier for the Payment Condition. responses: '200': description: Payment Condition accepted content: application/json: schema: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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é '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: PATRON_NOT_AUTHORIZED: description: The Payment Condition is `awaiting-merchant`, therefore the patron is not authorized to accept the condition. value: message: PATRON_NOT_AUTHORIZED MERCHANT_NOT_AUTHORIZED: description: The Payment Condition is `awaiting-patron`, therefore the merchant is not authorized to accept the condition. value: message: MERCHANT_NOT_AUTHORIZED CONDITION_ALREADY_SET: description: The Payment Condition has already been accepted or declined. value: message: CONDITION_ALREADY_SET /api/payment-requests/{paymentRequestId}/conditions/{conditionId}/decline: post: x-method: POST x-path: /api/payment-requests/{paymentRequestId}/conditions/{conditionId}/decline operationId: declinePaymentCondition summary: Decline a Payment Condition description: 'Decline a Payment Condition listed in `merchantConditions` with status `awaiting-merchant`. Returns a Payment Activity.' tags: - payment-requests parameters: - name: paymentRequestId in: path required: true schema: type: string example: MhocUmpxxmgdHjr7DgKoKw description: The Payment Request id. - name: conditionId in: path required: true schema: type: string example: '1' description: An enumerated identifier for the Payment Condition. responses: '200': description: Payment Condition declined content: application/json: schema: x-title: Payment Activity Model x-intro: '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`. ' type: object properties: id: type: string description: The unique identifier of the Payment Activity. type: type: string description: The [Payment Activity Type](#payment-activity-types). value: x-type: monetary type: object description: The value of the Payment Activity. Must be less than 100000000 and positive. properties: amount: type: string currency: type: string paymentRequestId: type: string description: The Payment Request's id. merchantId: type: string example: 5efbe17d96c083633e2b9241 description: The Centrapay merchant id. merchantConfigId: type: string description: The Payment Request's [Merchant Config](/api/merchant-configs) id. merchantAccountId: type: string description: The Payment Request's Merchant [Account](/api/accounts) id. merchantName: type: string example: NZD Test Merchant description: The name of the merchant. createdAt: type: string format: date-time example: '2021-06-12T01:17:00.000Z' description: When the activity was created. createdBy: x-type: crn type: string description: The identity that created the activity. paymentRequestCreatedBy: x-type: crn type: string description: The identity that created the Payment Request. activityNumber: x-type: bignumber type: string description: Unique sequential number for the activity. shortCode: type: string description: A shorter id that can be used for up to two years. assetType: type: string description: The Asset Type for the `payment` or `refund` activity. external: type: boolean description: '`true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system.' cancellationReason: type: string description: The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. conditionId: type: integer description: The id of a Condition if the activity was for a Condition being accepted or declined. idempotencyKey: type: string description: Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. confirmationIdempotencyKey: type: string description: Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. preAuth: type: boolean description: '`true` if the related Payment Request is a Pre Auth.' paidBy: type: object description: Shows the [Paid By](#paid-by-model) when a Payment Request is paid. strategy: type: object description: Details about the specifics for a refund. See [Strategy Model](#strategy-model) examples: default: value: 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é '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: PATRON_NOT_AUTHORIZED: description: The Payment Condition is `awaiting-merchant`, therefore the patron is not authorized to decline the condition. value: message: PATRON_NOT_AUTHORIZED MERCHANT_NOT_AUTHORIZED: description: The Payment Condition is `awaiting-patron`, therefore the merchant is not authorized to decline the condition. value: message: MERCHANT_NOT_AUTHORIZED CONDITION_ALREADY_SET: description: The Payment Condition has already been accepted or declined. value: message: CONDITION_ALREADY_SET components: schemas: ApiError: type: object properties: message: type: string description: The error code. securitySchemes: ApiKey: type: apiKey in: header name: X-Api-Key x-origin: - url: https://raw.githubusercontent.com/centrapay/centrapay-docs/master/src/content/api/openapi/index.yaml format: openapi version: 3.0.0 fetched: '2026-10-09' note: Multi-file spec from github.com/centrapay/centrapay-docs (src/content/api/openapi/), bundled by resolving relative $refs; sources saved verbatim under openapi/_original/centrapay-docs/. Covers the Payment Requests section of the docs only.