Strictly Public API

Payment Requests

Endpointhttps://api.paywithzero.net/v1

API get list of paymentRequest

GET

https://api.paywithzero.net/v1

/public/payment-request

Returns a paginated list of payment requests as { meta: { count, totalPages, page, limit }, data: [...] }. Only requests created through this API are listed (from is forced to eCommerce). Money fields in order (amount, tax, discount) are in dollars. All other money fields (e.g. order.baseAmount, order.totalAmount, order.products[].cost/tax/discount/total) are returned unconverted, in cents.

API get list of paymentRequest › query Parameters

endDay

string

Filter by creation date, end of range (e.g. 2025-01-31)

startDay

string

Filter by creation date, start of range (e.g. 2025-01-01)

orderId

string

Filter by order id

limit

integer · min: 1

Items per page (default 10)

Default: 10

page

integer · min: 1

Page number (default 1)

Default: 1

API get list of paymentRequest › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

API get list of paymentRequest › Responses

Paginated payment requests. Money fields in dollars.

No data returned

GET/public/payment-request

curl --request GET \
  --url https://api.paywithzero.net/v1/public/payment-request \
  --header 'key-hash: YOUR_KEY_HASH'

shell

Example Responses

{
  "meta": {
    "count": 3,
    "totalPages": 1,
    "page": 1,
    "limit": 10
  },
  "data": [
    {
      "id": "639a094749aa3d51cf39be77",
      "order": {
        "currency": "USD",
        "discount": 0,
        "tax": 0.1,
        "products": [],
        "customValues": [],
        "amount": 0.02,
        "poNumber": "235"
      },
      "showBilling": false,
      "showShipping": false,
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdAt": "2022-12-14T17:35:03.994Z",
      "updatedAt": "2022-12-14T17:35:03.994Z",
      "deletedAt": null
    },
    {
      "id": "639a99721db388674bf6ab73",
      "order": {
        "currency": "USD",
        "discount": 0,
        "tax": 0.1,
        "products": [],
        "customValues": [],
        "amount": 0.02,
        "poNumber": "235"
      },
      "showBilling": false,
      "showShipping": false,
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdAt": "2022-12-15T03:50:10.735Z",
      "updatedAt": "2022-12-15T03:50:10.735Z",
      "deletedAt": null
    },
    {
      "id": "639a9b671db388674bf6ab75",
      "order": {
        "currency": "USD",
        "discount": 0,
        "tax": 0.1,
        "products": [],
        "customValues": [],
        "amount": 2,
        "poNumber": "235"
      },
      "showBilling": false,
      "showShipping": false,
      "createdBy": "[email protected]",
      "updatedBy": null,
      "createdAt": "2022-12-15T03:58:31.022Z",
      "updatedAt": "2022-12-15T13:58:13.061Z",
      "deletedAt": null
    }
  ]
}

json

application/json

API create paymentRequest

POST

https://api.paywithzero.net/v1

/public/payment-request

Create a new payment request with billing info and optional product line items.

amount / tax: integer amounts in cents (1000 = $10.00); responses return them converted to dollars (amount: 200 → 2, tax: 10 → 0.1).

currency: ignored; the merchant gateway currency is used.

clientId: ignored; derived from your API key (key-hash).

customValues: merchant-configured custom fields ({ key, label, value }); keys must exist in the merchant order metadata, unknown keys are rejected.

products: optional list of products.

API create paymentRequest › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

API create paymentRequest › Request Body

amount

number · required

Integer amount in cents (1000 = $10.00). Converted to dollars in responses (amount: 200 is returned as 2).

Example: 200

object · required

clientId

string

Ignored. Derived from your API key (key-hash).

showBilling

boolean

If Billing Address must show in Single Payment Page

showShipping

boolean

If Shipping Address must show in Single Payment Page

customerId

string

Customer identifier

currency

string

Ignored; the merchant gateway currency is used.

orderId

string

Order identifier

orderDescription

string

Order descriptions

tax

number

Integer amount in cents (1000 = $10.00). Converted to dollars in responses (tax: 10 is returned as 0.1).

Example: 10

poNumber

string

Order PO Number

object

products

array[]

Optional list of products.

object[]

Merchant-configured custom fields; unknown keys are rejected.

shipping

number · deprecated · required

Deprecated. Ignored for totals and validation; include any shipping fee in amount (and tax fields as applicable).

API create paymentRequest › Responses

Payment request created.

No data returned

POST/public/payment-request

curl --request POST \
  --url https://api.paywithzero.net/v1/public/payment-request \
  --header 'Content-Type: application/json' \
  --header 'key-hash: YOUR_KEY_HASH' \
  --data '
{
  "tax": 10,
  "amount": 200,
  "poNumber": "235",
  "customValues": [],
  "currency": "USD",
  "showBilling": false,
  "showShipping": false,
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}
'

shell

Example Request Body

{
  "tax": 10,
  "amount": 200,
  "poNumber": "235",
  "customValues": [],
  "currency": "USD",
  "showBilling": false,
  "showShipping": false,
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

json

application/json

Example Responses

{
  "id": "639b3751881451001df993bb",
  "order": {
    "currency": "USD",
    "discount": 0,
    "tax": 0.1,
    "amount": 2,
    "poNumber": "235",
    "customValues": [],
    "products": []
  },
  "showBilling": false,
  "showShipping": false,
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2022-12-15T15:03:45.481Z",
  "updatedAt": "2022-12-15T15:03:45.481Z",
  "deletedAt": null
}

json

application/json

API view paymentRequest by id

GET

https://api.paywithzero.net/v1

/public/payment-request/{id}

Retrieve a single payment request by ID. Ids belonging to another merchant return 404. Money fields in order (amount, tax, discount) are in dollars. All other money fields (e.g. order.baseAmount, order.totalAmount, order.products[].cost/tax/discount/total) are returned unconverted, in cents.

API view paymentRequest by id › path Parameters

id

string · required

Payment request ID

API view paymentRequest by id › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

API view paymentRequest by id › Responses

Payment request returned. Money fields in dollars.

No data returned

Delete a Payment request by ID

DELETE

https://api.paywithzero.net/v1

/public/payment-request/{id}

Soft-deletes a payment request (active: false, deletedAt set). Paid requests cannot be deleted (400). The response is always { "success": true }.

Delete a Payment request by ID › path Parameters

id

string · required

Payment request ID

Delete a Payment request by ID › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

Delete a Payment request by ID › Responses

Payment request deleted.

success

boolean

Taxes Tokenize

Strictly Public API

Payment Requests

Endpointhttps://api.paywithzero.net/v1

Download schema

API get list of paymentRequest

GET

https://api.paywithzero.net/v1

/public/payment-request

API get list of paymentRequest › query Parameters

endDay

string

Filter by creation date, end of range (e.g. 2025-01-31)

startDay

string

Filter by creation date, start of range (e.g. 2025-01-01)

orderId

string

Filter by order id

limit

integer · min: 1

Items per page (default 10)

Default: 10

page

integer · min: 1

Page number (default 1)

Default: 1

API get list of paymentRequest › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

API get list of paymentRequest › Responses

Paginated payment requests. Money fields in dollars.

No data returned

GET/public/payment-request

curl --request GET \
  --url https://api.paywithzero.net/v1/public/payment-request \
  --header 'key-hash: YOUR_KEY_HASH'

shell

Example Responses

{
  "meta": {
    "count": 3,
    "totalPages": 1,
    "page": 1,
    "limit": 10
  },
  "data": [
    {
      "id": "639a094749aa3d51cf39be77",
      "order": {
        "currency": "USD",
        "discount": 0,
        "tax": 0.1,
        "products": [],
        "customValues": [],
        "amount": 0.02,
        "poNumber": "235"
      },
      "showBilling": false,
      "showShipping": false,
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdAt": "2022-12-14T17:35:03.994Z",
      "updatedAt": "2022-12-14T17:35:03.994Z",
      "deletedAt": null
    },
    {
      "id": "639a99721db388674bf6ab73",
      "order": {
        "currency": "USD",
        "discount": 0,
        "tax": 0.1,
        "products": [],
        "customValues": [],
        "amount": 0.02,
        "poNumber": "235"
      },
      "showBilling": false,
      "showShipping": false,
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdAt": "2022-12-15T03:50:10.735Z",
      "updatedAt": "2022-12-15T03:50:10.735Z",
      "deletedAt": null
    },
    {
      "id": "639a9b671db388674bf6ab75",
      "order": {
        "currency": "USD",
        "discount": 0,
        "tax": 0.1,
        "products": [],
        "customValues": [],
        "amount": 2,
        "poNumber": "235"
      },
      "showBilling": false,
      "showShipping": false,
      "createdBy": "[email protected]",
      "updatedBy": null,
      "createdAt": "2022-12-15T03:58:31.022Z",
      "updatedAt": "2022-12-15T13:58:13.061Z",
      "deletedAt": null
    }
  ]
}

json

application/json

API create paymentRequest

POST

https://api.paywithzero.net/v1

/public/payment-request

Create a new payment request with billing info and optional product line items.

amount / tax: integer amounts in cents (1000 = $10.00); responses return them converted to dollars (amount: 200 → 2, tax: 10 → 0.1).

currency: ignored; the merchant gateway currency is used.

clientId: ignored; derived from your API key (key-hash).

customValues: merchant-configured custom fields ({ key, label, value }); keys must exist in the merchant order metadata, unknown keys are rejected.

products: optional list of products.

API create paymentRequest › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

API create paymentRequest › Request Body

amount

number · required

Integer amount in cents (1000 = $10.00). Converted to dollars in responses (amount: 200 is returned as 2).

Example: 200

object · required

clientId

string

Ignored. Derived from your API key (key-hash).

showBilling

boolean

If Billing Address must show in Single Payment Page

showShipping

boolean

If Shipping Address must show in Single Payment Page

customerId

string

Customer identifier

currency

string

Ignored; the merchant gateway currency is used.

orderId

string

Order identifier

orderDescription

string

Order descriptions

tax

number

Integer amount in cents (1000 = $10.00). Converted to dollars in responses (tax: 10 is returned as 0.1).

Example: 10

poNumber

string

Order PO Number

object

products

array[]

Optional list of products.

object[]

Merchant-configured custom fields; unknown keys are rejected.

shipping

number · deprecated · required

Deprecated. Ignored for totals and validation; include any shipping fee in amount (and tax fields as applicable).

API create paymentRequest › Responses

Payment request created.

No data returned

POST/public/payment-request

curl --request POST \
  --url https://api.paywithzero.net/v1/public/payment-request \
  --header 'Content-Type: application/json' \
  --header 'key-hash: YOUR_KEY_HASH' \
  --data '
{
  "tax": 10,
  "amount": 200,
  "poNumber": "235",
  "customValues": [],
  "currency": "USD",
  "showBilling": false,
  "showShipping": false,
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}
'

shell

Example Request Body

{
  "tax": 10,
  "amount": 200,
  "poNumber": "235",
  "customValues": [],
  "currency": "USD",
  "showBilling": false,
  "showShipping": false,
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

json

application/json

Example Responses

{
  "id": "639b3751881451001df993bb",
  "order": {
    "currency": "USD",
    "discount": 0,
    "tax": 0.1,
    "amount": 2,
    "poNumber": "235",
    "customValues": [],
    "products": []
  },
  "showBilling": false,
  "showShipping": false,
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2022-12-15T15:03:45.481Z",
  "updatedAt": "2022-12-15T15:03:45.481Z",
  "deletedAt": null
}

json

application/json

API view paymentRequest by id

GET

https://api.paywithzero.net/v1

/public/payment-request/{id}

API view paymentRequest by id › path Parameters

id

string · required

Payment request ID

API view paymentRequest by id › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

API view paymentRequest by id › Responses

Payment request returned. Money fields in dollars.

No data returned

Delete a Payment request by ID

DELETE

https://api.paywithzero.net/v1

/public/payment-request/{id}

Soft-deletes a payment request (active: false, deletedAt set). Paid requests cannot be deleted (400). The response is always { "success": true }.

Delete a Payment request by ID › path Parameters

id

string · required

Payment request ID

Delete a Payment request by ID › Headers

key-hash

string · required

Security key hash issued to your integration (merchant dashboard: Administration → Security Keys).

Delete a Payment request by ID › Responses

Payment request deleted.

success

boolean

Taxes Tokenize