Requests

requests.create

This endpoint creates a request for an asset transfer.

HTTP Request

POST https://centrapay.com/api/requests.create

Parameters

Name Example Required Description
asset “NZD” Required The currency or other asset class denomination
amount 1020 Required The amount in the minimum divisible units of the deonminated asset requested
merchantId “495e7146-1b9…” Required The unique reference of the merchant entity creating the request
clientId “1df56043-309…” Optional The unique reference to the merchant-specific client’s configuration
externalReference “request1234” Optional The issuer-generated unique reference for the request
description “New bike” Optional The issuer-generated payment description
notifyUrl “/api/service.notify” Optional The URL that will receive the webhook POST requests

Response (200)

{
    "requestId": "64b023fc-f17f-4f3d-afb6-0401306cd550",
    "merchantId": "495e7146-1b9...",
    "externalReference": "request1234",
    "denomination": {
        "amount": 1020,
        "asset": "NZD"
    },
    "payments": [
        {
            "amount": 1320000000000000,
            "account": "0x3c296276577e5fb318a47989cb314123528d88da",
            "ledger": "g.crypto.ethereum.mainnet.0x1122b6a0e00dce0563082b6e2953f3a943855c1f",
            "methods": ["qr_code","nfc"]
        },
        {
            "amount": 1020,
            "ledger": "g.centrapay.pocketvouchers.voucher1",
            "methods": ["auth_alphanumeric"]
        }
    ],
    "requestCode": "JL9mAFVaK71wTDVoM6NH7w",
    "description": "New bike"",
    "status": "new",
    "createdAt": "2018-04-06T04:36:54Z",
    "updatedAt": "2018-04-06T04:36:54Z",
    "clientId": "1df56043-309...",
    "notifyUrl": "http://localhost:8080/api/service.notify"
}

Response Properties

Property Description
requestId The unique identifier for the request
merchantId The unique identifier for the merchant entity issuing the request
externalReference The issuer-generated unique reference for the request
denomination.amount The amount in the minimum divisible units of the deonminated asset requested
denomination.asset The currency or other asset class requested
payments.amount Amount of the asset that would satisy as full payment for the request
payments.account Account to which the transfer should be made to satisfy the request
payments.ledger Ledger at which the transfer should be recorded to satisfy the request
payments.methods Collection of values indicating how the payment should be initiated. Possible values are “qr” and/or “nfc” or “auth_alphanumeric” or “auth_numeric”
requestCode The code to be presented in the QR code or transmitted to a wallet over NFC
description A description supplied by the request issuer
status “new”, “paid”, “canceled”, or “expired”
createdAt Timestamp at which the request was created
updatedAt Timestamp at which the request was last updated
clientId The unique reference to the merchant-specific client’s configuration
notifyUrl The URL that will receive the webhook POST requests

Sample Request

curl -d "asset=NZD&amount=1020&merchantId=merchant1234&description=My+request+description&externalReference=request1234" -X POST https://centrapay.com/api/requests.create

requests.info

This endpoint issues a request for a payment that would satisfy the request.

HTTP Request

GET https://centrapay.com/api/requests.info

Parameters

Name Example Required Description
requestId “64b023fc-f17f-4f3d-afb6-0401306cd550” Required The request to be paid

Response (200)

{
    "requestId": "64b023fc-f17f-4f3d-afb6-0401306cd550",
    "merchantId": "495e7146-1b9...",
    "externalReference": "request1234",
    "denomination": {
        "amount": 1020,
        "asset": "NZD"
    },
    "payments": [
        {
            "amount": 1320000000000000,
            "account": "0x3c296276577e5fb318a47989cb314123528d88da",
            "ledger": "g.crypto.ethereum.mainnet.0x1122b6a0e00dce0563082b6e2953f3a943855c1f",
            "methods": ["qr_code","nfc"]
        },
        {
            "amount": 1020,
            "account": "",
            "ledger": "g.centrapay.pocketvouchers.voucher1",
            "methods": ["auth_alphanumeric"]
        }
    ],
    "paidBy": {
        "amount": 1320000000000000,
        "account": "0x3c296276577e5fb318a47989cb314123528d88da",
        "ledger": "g.crypto.ethereum.mainnet.0x1122b6a0e00dce0563082b6e2953f3a943855c1f",
        "paidAt": "2018-04-06T04:36:54Z",
        "responseCode": "00",
        "authCode": "0xf230b05336e18588068369c30b56bcb6192785987c6ca00f2afd2babc9769540",
        "type": "CENNZ",
        "receipt": "Ki0tLS0tLS0tLS0tRUZUUE9TLS0tLS0tLS...",
        "settlementDate": "2018-04-06T00:00:00Z"
    },
    "requestCode": "centrapay:68747470733A2F2F63656E74726170...",
    "description": "My request description",
    "status": "paid",
    "createdAt": "2018-04-06T04:36:54Z",
    "updatedAt": "2018-04-06T05:53:54Z",
    "clientId": "1df56043-309...",
    "notifyUrl": "http://localhost:8080/api/service.notify"
}

Response Properties

Property Description
requestId The unique identifier for the request
merchantId The unique identifier for the merchant entity issuing the request
externalReference The issuer-generated unique reference for the request
denomination.amount The amount in the minimum divisible units of the denominated asset requested
denomination.asset The currency or other asset class requested
payments.amount Amount of the asset that would satisy as full payment for the request
payments.account Account to which the transfer should be made to satisfy the request
payments.ledger Ledger at which the transfer should be recorded to satisfy the request
payments.methods Collection of values indicating how the payment should be initiated. Possible values are “qr” and/or “nfc” or “auth_alphanumeric” or “auth_numeric”
paidBy.amount The quantity of minimum divisible units of the asset that were transferred
paidBy.account The account to which the transfer was made
paidBy.ledger The ledger of on which the transfer took place
paidBy.paidAt The timestamp at which the transfer took
paidBy.responseCode The text description of the request
paidBy.authCode Code ascribed to the transfer indicating that it has been authorized
paidBy.type The payment type used by the issuer to reconcile settlement accounts. This could be card type
paidBy.receipt The base64 encoded receipt to be printed for the payer
paidBy.settlementDate The date at which the transfer settles to the request issuer
requestCode The code to be presented in the QR code or transmitted to a wallet over NFC
description A description supplied by the request issuer
status “new”, “paid”, “canceled”, or “expired”
createdAt Timestamp at which the request was created
updatedAt Timestamp at which the request was last updated
expiresAt Timestamp at which the request will be no longer valid an payment should not be made
clientId The unique reference to the merchant-specific client’s configuration
notifyUrl The URL that will receive the webhook POST requests

Sample Request

curl -d "requestId=64b023fc-f17f-4f3d-afb6-0401306cd550" -X GET https://centrapay.com/api/requests.info

requests.pay

This endpoint accepts a request for an asset transfer in payment of a request.

HTTP Request

POST https://centrapay.com/api/requests.pay

Parameters

Name Example Required Description
requestId “64b023fc-f17f-4f3d-afb6-0401306cd550” Required The request to be paid
authorization “ILOVECENTRAPAY” Required The value required to authorize the payment
ledger “g.centrapay.pocketvouchers.voucher1” Required The ledger at which the authorization should be processed

Response (200)

{
    "requestId": "64b023fc-f17f-4f3d-afb6-0401306cd550",
    "merchantId": "495e7146-1b9...",
    "externalReference": "request1234",
    "denomination": {
        "amount": 1020,
        "asset": "NZD"
    },
    "payments": [
        {
            "amount": 1320000000000000,
            "account": "0x3c296276577e5fb318a47989cb314123528d88da",
            "ledger": "g.crypto.ethereum.mainnet.0x1122b6a0e00dce0563082b6e2953f3a943855c1f",
            "methods": ["qr_code","nfc"]
        },
        {
            "amount": 1020,
            "account": "",
            "ledger": "g.centrapay.pocketvouchers.voucher1",
            "methods": ["auth_alphanumeric"]
        }
    ],
    "paidBy": {
        "amount": 1020,
        "account": "",
        "ledger": "g.centrapay.pocketvouchers.voucher1",
        "paidAt": "2018-04-06T04:36:54Z",
        "responseCode": "00",
        "authCode": "9876",
        "type": "POCKET_VOUCHER",
        "receipt": "Ki0tLS0tLS0tLS0tRUZUUE9TLS0tLS0tLS...",
        "settlementDate": "2018-04-06T00:00:00Z"
    },
    "requestCode": "centrapay:68747470733A2F2F63656E74726170...",
    "description": "My request description",
    "status": "paid",
    "createdAt": "2018-04-06T04:36:54Z",
    "updatedAt": "2018-04-06T05:53:54Z",
}

Response Properties

Property Description
requestId The unique identifier for the request
merchantId The unique identifier for the merchant entity issuing the request
externalReference The issuer-generated unique reference for the request
denomination.amount The amount in the minimum divisible units of the deonminated asset requested
denomination.asset The currency or other asset class requested
payments.amount Amount of the asset that would satisy as full payment for the request
payments.account Account to which the transfer should be made to satisfy the request
payments.ledger Ledger at which the transfer should be recorded to satisfy the request
payments.methods Collection of values indicating how the payment should be initiated. Possible values are “qr” and/or “nfc” or “auth_alphanumeric” or “auth_numeric”
paidBy.amount The quantity of minimum divisible units of the asset that were transferred
paidBy.account The account to which the transfer was made
paidBy.ledger The ledger of on which the transfer took place
paidBy.paidAt The timestamp at which the transfer took
paidBy.responseCode The text description of the request
paidBy.authCode Code ascribed to the transfer indicating that it has been authorized
paidBy.type The payment type used by the issuer to reconcile settlement accounts. This could be card type
paidBy.receipt The base64 encoded receipt to be printed for the payer
paidBy.settlementDate The date at which the transfer settles to the request issuer
requestCode The code to be presented in the QR code or transmitted to a wallet over NFC
description A description supplied by the request issuer
status “new”, “paid”, “canceled”, or “expired”
createdAt Timestamp at which the request was created
updatedAt Timestamp at which the request was last updated

Sample Request

curl -d "requestId=64b023fc-f17f-4f3d-afb6-0401306cd550&ledger=g.centrapay.pocketvouchers.voucher1&paymentAuthorization=1234123412341234" -X POST https://centrapay.com/api/requests.pay

requests.cancel

Cancels a pending request.

HTTP Request

POST https://centrapay.com/api/requests.cancel

Parameters

Name Example Required Description
requestId “64b023fc-f17f-4f3d-afb6-0401306cd550” Required The request to be cancelled

Response (200)

{
    "requestId": "64b023fc-f17f-4f3d-afb6-0401306cd550",
    "merchantId": "495e7146-1b9...",
    "externalReference": "request1234",
    "denomination": {
        "amount": 1020,
        "asset": "NZD"
    },
    "payments": [
        {
            "amount": 1320000000000000,
            "account": "0x3c296276577e5fb318a47989cb314123528d88da",
            "ledger": "g.crypto.ethereum.mainnet.0x1122b6a0e00dce0563082b6e2953f3a943855c1f",
            "methods": ["qr_code","nfc"]
        },
        {
            "amount": 1020,
            "account": "",
            "ledger": "g.centrapay.pocketvouchers.voucher1",
            "methods": ["auth_alphanumeric"]
        }
    ],
    "requestCode": "centrapay:68747470733A2F2F63656E74726170...",
    "description": "My request description",
    "status": "cancelled",
    "createdAt": "2018-04-06T04:36:54Z",
    "updatedAt": "2018-04-06T05:46:54Z",
    "clientId": "1df56043-309...",
    "notifyUrl": "http://localhost:8080/api/service.notify"
}

Response Properties

Property Description
requestId The unique identifier for the request
merchantId The unique identifier for the merchant entity issuing the request
externalReference The issuer-generated unique reference for the request
denomination.amount The amount in the minimum divisible units of the deonminated asset requested
denomination.asset The currency or other asset class requested
payments.amount Amount of the asset that would satisy as full payment for the request
payments.account Account to which the transfer should be made to satisfy the request
payments.ledger Ledger at which the transfer should be recorded to satisfy the request
payments.methods Collection of values indicating how the payment should be initiated. Possible values are “qr” and/or “nfc” or “auth_alphanumeric” or “auth_numeric”
requestCode The code to be presented in the QR code or transmitted to a wallet over NFC
description A description supplied by the request issuer
status “new”, “paid”, “canceled”, or “expired”
createdAt Timestamp at which the request was created
updatedAt Timestamp at which the request was last updated
clientId The unique reference to the merchant-specific client’s configuration
notifyUrl The URL that will receive the webhook POST requests

Sample Request

curl -d "requestId=64b023fc-f17f-4f3d-afb6-0401306cd550" -X POST https://centrapay.com/api/requests.cancel