Legacy Payment Requests

Centrapay Payment Requests are serviced via two sets of endpoints; the “next” version (documented Payment Requests) and the “legacy” version (documented on this page). Use of legacy endpoints for new integrations is discouraged where alternative endpoints have been provided.

Legacy Payment Request endpoints also have interactive Swagger documentation.

Contents

• Operations
  • Creating a payment request
  • Getting the information about a payment request
  • Paying a payment request
  • Cancelling a payment request
  • Voiding a payment request
  • Refunding a transaction
• Webhooks
  • Life-cycle Events That Trigger Webhooks
  • Webhook Payload
  • Webhook JWT Validation
  • Decoded Webhook JWT Examples

Operations

Creating a payment request

Swagger Docs

POST /payments/api/requests.create

curl -X POST https://service.centrapay.com/payments/api/requests.create \
  -H "X-Api-Key: $api_key" \
  -d merchantId=5efbe17d96c083633e2b9241 \
  -d clientId=5efbe2fb96c08357bb2b9242 \
  -d amount=300 \
  -d asset=NZD

Required Parameters

See Asset Types for the list of possible asset values for each Asset Type.

Optional Parameters

Error Responses

Getting the information about a payment request

Swagger Docs

GET /payments/api/requests.info

curl -G https://service.centrapay.com/payments/api/requests.info \
  -H "X-Api-Key: $api_key" \
  -d requestId=TyqV56mEkNLUeiY2QskHNR

Required Parameters

Error Responses

Example response payload of a new request

{
  "requestId": "TyqV56mEkNLUeiY2QskHNR",
  "shortCode": "CP-C7F-ZS5",
  "merchantId": "5efbe17d96c083633e2b9241",
  "merchantName": "NZD Test Merchant",
  "clientId": "5efbe2fb96c08357bb2b9242",
  "denomination": {
    "asset": "NZD",
    "amount": 100
  },
  "payments": [
    {
      "ledger": "centrapay.nzd.test",
      "amount": 100,
      "methods": [
        "qr_code"
      ]
    }
  ],
  "qrCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
  "requestCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
  "status": "new",
  "createdAt": "2021-11-29T23:04:54.253Z",
  "updatedAt": "2021-11-29T23:04:54.253Z",
  "liveness": "test",
  "paymentExpirySeconds": 120
}

Example response payload of a paid request

{
  "requestId": "TyqV56mEkNLUeiY2QskHNR",
  "shortCode": "CP-C7F-ZS5",
  "merchantId": "5efbe17d96c083633e2b9241",
  "merchantName": "NZD Test Merchant",
  "clientId": "5efbe2fb96c08357bb2b9242",
  "denomination": {
    "asset": "NZD",
    "amount": 100
  },
  "payments": [
    {
      "ledger": "centrapay.nzd.test",
      "amount": 100,
      "methods": [
        "qr_code"
      ]
    }
  ],
  "qrCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
  "requestCode": "https://app.centrapay.com/pay/TyqV56mEkNLUeiY2QskHNR",
  "status": "paid",
  "createdAt": "2021-11-29T23:04:54.253Z",
  "updatedAt": "2021-11-29T23:05:38.254Z",
  "liveness": "test",
  "paymentExpirySeconds": 120,
  "paidBy": {
    "ledger": "centrapay.nzd.test",
    "type": "centrapay.nzd.test",
    "authCode": "3MhaANvdS79qhvAj6nYFNT",
    "responseCode": "1234",
    "receipt": "",
    "v2": true,
    "paidAt": "2021-11-29T23:05:38.000Z",
    "amount": 100,
    "account": "3MhaANvdS79qhvAj6nYFNT",
    "transactionId": "TyqV56mEkNLUeiY2QskHNR",
    "description": "Centrapay Test NZD",
    "settlementDate": "2021-11-29T23:05:38.000Z",
    "assetTotals": [
      {
        "type": "centrapay.nzd.test",
        "description": "Centrapay Test NZD",
        "settlementDate": "2021-11-29T23:05:38.000Z",
        "total": {
          "amount": "100",
          "currency": "NZD"
        }
      }
    ]
  }
}

Paying a payment request

Swagger Docs

POST /payments/api/requests.pay

curl -X POST https://service.centrapay.com/payments/api/requests.pay \
  -H "X-Api-Key: $api_key" \
  -d authorization=12345678 \
  -d ledger=g.pocketvouchers.pv \
  -d requestId=7d2b1d52-b609-4ccd-b4cc-c4a9af881bd9

Required Parameters

Expected Ledger and Authorization Values

The “ledger” parameter indicates which payment option has been selected to pay the payment request. The selected payment option must be one of the options available for the payment request as per the payments array in the requests.create and requests.info responses.

The table below lists the possible ledger and authorization param values. The asset type is the value used to configure the merchant. The ledger param value is returned with the payment request info as payments[].ledger.

Centrapay Asset Permissions

To pay with a Centrapay asset or wallet ledger the user (identified by the API Key or identity token) must have permission to redeem the asset or transfer funds from the specified wallet.

Testing Pocket Vouchers

To test Pocket Vouchers, generate a test value voucher by texting “CENTRALBONUS” to 393. You will then receive a response text containing an 8 digit voucher code that has $20 of loaded credit. The received code is only valid for two weeks from the issue date. You might get charged your standard text rates from your provider.

Error Responses

Cancelling a payment request

Swagger Docs

POST /payments/api/requests.cancel

curl -X POST https://service.centrapay.com/payments/api/requests.cancel \
  -H "X-Api-Key: $api_key" \
  -d requestId=a95b3b0d-1278-4613-8772-20d146065a2e

Required Parameters

Error Responses

Voiding a payment request

Swagger Docs

POST /payments/api/requests.void

curl -X POST https://service.centrapay.com/payments/api/requests.void \
  -H "X-Api-Key: $api_key" \
  -d requestId=a95b3b0d-1278-4613-8772-20d146065a2e

Required Parameters

Error Responses

Voiding a payment request can cause it to be cancelled or refunded. Therefore, this endpoint can give the same error responses as requests.cancel and transactions.refund. After 24 hours voiding a payment request will be disallowed, however a refund can still be made against the payment request if it has been paid successfully.

Refunding a transaction

Swagger Docs

POST /payments/api/transactions.refund

curl -X POST https://service.centrapay.com/payments/api/transactions.refund \
  -H "X-Api-Key: $api_key" \
  -d transactionId=7d2b1d52-b609-4ccd-b4cc-c4a9af881bd9 \
  -d amount=100

Refunding a transaction can be done with or without an external reference.

Refund without external reference

If you refund a transaction without providing an external reference, you will get a successful response for the first request and then an ALREADY_REFUNDED message for any refund requests that follow for the same transaction, unless an external reference is provided.

Refund with external reference

If you provide an external reference then a transaction can be refunded multiple times provided that the external reference is unique for each refund request. When a duplicate external reference is provided when attempting to refund the same transaction we return a successful response if the amount of the request is the same both times but do not process another refund, this is because we assume it to be a repeat request. If the amount is different you will get a REPEAT_REFERENCE error message.

Refund a Pre Auth Payment Request with Confirmations

The legacy refund endpoint cannot be used to refund Pre Auth Payment Requests with Confirmations. Please use the current refund endpoint instead.

Required Parameters for one time refund

Additional required Parameter for multiple refunds

Error Responses

Webhooks

Webhook notifications are sent for significant Payment life-cycle events. The Webhook endpoint is notified by sending an HTTP POST request to the notifyUrl defined in the Payment Request.

Life-cycle Events That Trigger Webhooks

The supported event types that will be notified to the Payment Requests webhook and the associated “transactionType” value that will be sent in the payload are:

Payment Request Cancelled

A payment request can be cancelled by either calling the requests.cancel or requests.void endpoint before a request has been paid successfully. When a request has been cancelled we send a JWT that when decoded matches the Payment Request Cancelled example in the Decoded Webhook JWT Examples section below.

Payment Request Expired

A payment request expires two minutes after being created if it hasn’t been cancelled, or paid. When a request has expired we send a JWT that when decoded matches the Payment Request Cancelled example in the Decoded Webhook JWT Examples section below with the transactionType set to EXPIRED.

Transaction Completed

A transaction is considered complete when requests.pay is called with parameters that satisfy a payment request and the request has been paid successfully. When a transaction has been completed we send a JWT that when decoded matches the Transaction Completed example in the Decoded Webhook JWT Examples section below.

Transaction Refunded

A transaction can be refunded one to many times and each time a transaction has been refunded successfully we notify the webhook associated with the original payment request. A transaction can be refunded when transactions.refund has been called for a partial or full refund, or when requests.void is called for a request that has been paid. When a transaction has been refunded we send a JWT that when decoded matches the Transaction Completed example in the Decoded Webhook JWT Examples section below but with transactionType set to REFUND.

Webhook Payload

The body of the webhook is a JSON document with the following format:

{
  "token": "${JWT}"
}

The decoded JWT will contain a “transaction” property with a “transactionType” that indicates the event type. Depending on the type of event, the payload will also contain additional details about the transaction and payment request. For example:

{
  "transaction": {
    "transactionType": "REFUND",
    "request": {
      "requestId": "bec358bf-edb5-4633-a785-a95cc281d3b7",
      "denomination": {
        "asset": "NZD",
        "amount": "100"
      }
    }
  }
}

Webhook Payload Fields

Webhook JWT Validation

A webhook JWT can be validated by checking the signature against the Centrapay Webhook public key:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt+vW2fE0mLLmdzJtYrz7J9q/yEXl
gmIjCXdv3VNvYfTsaBO5PJNiaD3l9lD8PzEQu31ePsOG81mDVuo40+dgLg==
-----END PUBLIC KEY-----

Decoded Webhook JWT Examples

Transaction Completed Successfully

{
  "transaction": {
    "transactionId": "E6ctbmgmkgZ3xnPk3BkGvb",
    "transactionType": "PURCHASE",
    "ledger": "g.crypto.bitcoin.mainnet",
    "state": "completed",
    "amount": 2000,
    "request": {
      "requestId": "0FmbuirpQG4iuy6xAV9R1p",
      "merchantId": "613919a417bea000290e97e3",
      "externalReference": "12345sixseveneightnineten",
      "denomination": {
        "asset": "NZD",
        "amount": 2000
      }
    },
    "createdAt": "2018-10-02T00:29:09.307Z",
    "updatedAt": "2018-10-02T00:29:11.383Z",
    "type": "BITCOIN",
    "authCode": "961241"
  }
}

Payment Request Cancelled

{
  "transaction": {
    "transactionType": "CANCELLED",
    "request": {
      "requestId": "0FmbuirpQG4iuy6xAV9R1p",
      "merchantId": "613919a417bea000290e97e3",
      "clientId": "613919a417bea000290e97e4",
      "denomination": {
        "asset": "NZD",
        "amount": "1"
      }
    }
  }
}