Skip to content
/Payments

Helix-Pay API (1.0.0)

API documentation for the Helix-Pay API

Download OpenAPI description
external.gen.json
external.gen.yaml
Languages
Servers
Mock server
https://docs.helix-pay.net/_mock/apis/external.gen/
Production server
https://api.helix-pay.net/v1/

Payments

Operations related to payments

Operations

List payments

Request

Get a paginated list of all payments made by consumers

Security
ApiKeyAuth
Query
limitinteger[ 1 .. 100 ]

The maximum number of payments to return

Default 10
offsetinteger>= 0

The number of payments to skip

Default 0
statusstring

Filter payments by status

Enum"pending""completed""failed"
curl -i -X GET \
  'https://docs.helix-pay.net/_mock/apis/external.gen/payments?limit=10&offset=0&status=pending' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
dataArray of objects(PaymentSchema)
metadataobject
Response
application/json
{
  "data": [
    { … }
  ],
  "metadata": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Create a new payment

Request

Creates a new payment request

Security
ApiKeyAuth
Bodyapplication/jsonrequired
amountintegerrequired

The payment amount in the lowest currency unit (e.g. cents)

Example: 1099
currencystring(currency-code)required
Enum"USD""EUR""GBP"
Example: "EUR"
descriptionstringrequired

A short description of the payment

Example: "Payment for order #1234"
return_urlsobject

The URLs to redirect the user to after payment, depending on the payment status. If you want to process both statuses on the same page, you can use the same URL for both properties.

destination_wallet_idstring

The ID of the wallet to which the payment will be sent. This is required for marketplace type flows.

Example: "wlt_7uAd21uizm5p1psa"
metadataobject

Additional metadata for the payment. We will store this as part of the payment request and return it with every GET request for a specific payment.

Example: {"order_id":"1234","customer_id":"5678"}
expires_atstring

The time after which the payment request will expire. This should be in ISO 8601 format. Defaults to 60 minutes after the payment request is created.

Example: "2022-01-01T12:00:00Z"
payment_configobject(PaymentConfigSchema)
billing_addressobject

The billing address for the payment

curl -i -X POST \
  https://docs.helix-pay.net/_mock/apis/external.gen/payments \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "amount": 1000,
    "currency": "EUR",
    "description": "Payment for order #1989188",
    "payment_method_code": "CARD",
    "return_urls": {
      "failure": "https://example.com/payments/failure",
      "success": "https://example.com/payments/success"
    }
  }'

Responses

Payment request created

Bodyapplication/json
idstring

The unique identifier for the payment

Example: "pay_7uAd21uizm5p1psa"
amountinteger

The payment amount in the lowest currency unit (e.g. cents)

Example: 1099
currencystring

The payment currency

Example: "EUR"
descriptionstring

A short description of the payment

Example: "Payment for order #1234"
checkout_urlstring

The URL to redirect the user to for payment

Example: "https://checkout.helixpay.io/pay_7uAd21uizm5p1psa"
return_urlsobject(ReturnUrlsSchema)
destination_wallet_idstring

The ID of the wallet to which the payment will be sent

Example: "wlt_7uAd21uizm5p1psa"
metadataobject

Additional metadata for the payment

Example: {"order_id":"1234","customer_id":"5678"}
payment_status_codestring

The status of the payment request. This will always be "Created" for a newly created payment request.

Example: "CREATED"
payment_method_codestring

The payment method used for the payment

Example: "card"
test_modeboolean

If the payment is a test payment for sandbox testing

Example: false
breakdownobject(PaymentBreakdownSchema)
refundobject(RefundPaymentResponseSchema)
billing_addressobject(BillingDetailsSchema)
payment_configobject(PaymentConfigSchema)
created_atstring(date-time)

The date and time the payment request was created

Example: "2021-01-01T12:00:00Z"
updated_atstring(date-time)

The date and time the payment request was last updated

Example: "2021-01-01T12:00:00Z"
expires_atstring(date-time)

The time after which the payment request will expire

Example: "2022-01-01T12:00:00Z"
completed_atstring(date-time)

The time at which the payment was completed

Example: "2022-01-01T12:00:00Z"
Response
application/json
{
  "amount": 1000,
  "checkout_url": "https://checkout.helix-pay.net/checkout/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "created_at": "2025-01-16T00:00:00.00000Z",
  "currency": "EUR",
  "description": "Payment for order #1989188",
  "id": "pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "payment_method_code": "CARD",
  "payment_status_code": "CREATED",
  "return_urls": {
    "failure": "https://example.com/payments/failure",
    "success": "https://example.com/payments/success"
  },
  "test_mode": false,
  "updated_at": "2025-01-16T00:00:00.00000Z"
}

Get payment details

Request

Get details for a specific payment

Security
ApiKeyAuth
Path
payment_idstringrequired

The unique identifier for the payment

Example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/payments/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9 \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
idstring

The unique identifier for the payment

Example: "pay_7uAd21uizm5p1psa"
amountinteger

The payment amount in the lowest currency unit (e.g. cents)

Example: 1099
currencystring

The payment currency

Example: "EUR"
descriptionstring

A short description of the payment

Example: "Payment for order #1234"
checkout_urlstring

The URL to redirect the user to for payment

Example: "https://checkout.helixpay.io/pay_7uAd21uizm5p1psa"
return_urlsobject(ReturnUrlsSchema)
destination_wallet_idstring

The ID of the wallet to which the payment will be sent

Example: "wlt_7uAd21uizm5p1psa"
metadataobject

Additional metadata for the payment

Example: {"order_id":"1234","customer_id":"5678"}
payment_status_codestring

The status of the payment request. This will always be "Created" for a newly created payment request.

Example: "CREATED"
payment_method_codestring

The payment method used for the payment

Example: "card"
test_modeboolean

If the payment is a test payment for sandbox testing

Example: false
breakdownobject(PaymentBreakdownSchema)
refundobject(RefundPaymentResponseSchema)
billing_addressobject(BillingDetailsSchema)
payment_configobject(PaymentConfigSchema)
created_atstring(date-time)

The date and time the payment request was created

Example: "2021-01-01T12:00:00Z"
updated_atstring(date-time)

The date and time the payment request was last updated

Example: "2021-01-01T12:00:00Z"
expires_atstring(date-time)

The time after which the payment request will expire

Example: "2022-01-01T12:00:00Z"
completed_atstring(date-time)

The time at which the payment was completed

Example: "2022-01-01T12:00:00Z"
Response
application/json
{
  "amount": 1000,
  "checkout_url": "https://checkout.helix-pay.net/checkout/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "created_at": "2025-01-16T00:00:00.00000Z",
  "currency": "EUR",
  "description": "Payment for order #1989188",
  "id": "pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "payment_method_code": "CARD",
  "payment_status_code": "CREATED",
  "return_urls": {
    "failure": "https://example.com/payments/failure",
    "success": "https://example.com/payments/success"
  },
  "test_mode": false,
  "updated_at": "2025-01-16T00:00:00.00000Z"
}

Update payment status

Request

Update the details of a specific payment

Security
ApiKeyAuth
Path
payment_idstringrequired

The unique identifier for the payment

Example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Bodyapplication/jsonrequired
descriptionstring
metadataobject
curl -i -X PATCH \
  https://docs.helix-pay.net/_mock/apis/external.gen/payments/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9 \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "description": "string",
    "metadata": {}
  }'

Responses

Payment updated

Bodyapplication/json
idstring

The unique identifier for the payment

Example: "pay_7uAd21uizm5p1psa"
amountinteger

The payment amount in the lowest currency unit (e.g. cents)

Example: 1099
currencystring

The payment currency

Example: "EUR"
descriptionstring

A short description of the payment

Example: "Payment for order #1234"
checkout_urlstring

The URL to redirect the user to for payment

Example: "https://checkout.helixpay.io/pay_7uAd21uizm5p1psa"
return_urlsobject(ReturnUrlsSchema)
destination_wallet_idstring

The ID of the wallet to which the payment will be sent

Example: "wlt_7uAd21uizm5p1psa"
metadataobject

Additional metadata for the payment

Example: {"order_id":"1234","customer_id":"5678"}
payment_status_codestring

The status of the payment request. This will always be "Created" for a newly created payment request.

Example: "CREATED"
payment_method_codestring

The payment method used for the payment

Example: "card"
test_modeboolean

If the payment is a test payment for sandbox testing

Example: false
breakdownobject(PaymentBreakdownSchema)
refundobject(RefundPaymentResponseSchema)
billing_addressobject(BillingDetailsSchema)
payment_configobject(PaymentConfigSchema)
created_atstring(date-time)

The date and time the payment request was created

Example: "2021-01-01T12:00:00Z"
updated_atstring(date-time)

The date and time the payment request was last updated

Example: "2021-01-01T12:00:00Z"
expires_atstring(date-time)

The time after which the payment request will expire

Example: "2022-01-01T12:00:00Z"
completed_atstring(date-time)

The time at which the payment was completed

Example: "2022-01-01T12:00:00Z"
Response
application/json
{
  "amount": 1000,
  "checkout_url": "https://checkout.helix-pay.net/checkout/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "created_at": "2025-01-16T00:00:00.00000Z",
  "currency": "EUR",
  "description": "Payment for order #1989188",
  "id": "pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "payment_method_code": "CARD",
  "payment_status_code": "CREATED",
  "return_urls": {
    "failure": "https://example.com/payments/failure",
    "success": "https://example.com/payments/success"
  },
  "test_mode": false,
  "updated_at": "2025-01-16T00:00:00.00000Z"
}

Refund a payment

Request

Request a refund for a specific payment

Security
ApiKeyAuth
Path
payment_idstringrequired

The unique identifier for the payment

Example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Bodyapplication/jsonrequired
amountintegerrequired

The amount to refund. Up to the payment amount

Example: 1000
reason_codestringrequired

The reason for the refund

Enum"FRADULENT""CUSTOMER_REQUESTED""DUPLICATE""OTHER"
Example: "CUSTOMER_REQUESTED"
other_reasonstring

Required if reason_code is OTHER

Example: "Order Cancelled"
curl -i -X POST \
  https://docs.helix-pay.net/_mock/apis/external.gen/payments/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/refund \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "amount": 1000,
    "reason_code": "CUSTOMER_REQUESTED",
    "other_reason": "Order Cancelled"
  }'

Responses

Refund request created

Bodyapplication/json
idstring

The unique identifier for the payment

Example: "pay_7uAd21uizm5p1psa"
amountinteger

The payment amount in the lowest currency unit (e.g. cents)

Example: 1099
currencystring

The payment currency

Example: "EUR"
descriptionstring

A short description of the payment

Example: "Payment for order #1234"
checkout_urlstring

The URL to redirect the user to for payment

Example: "https://checkout.helixpay.io/pay_7uAd21uizm5p1psa"
return_urlsobject(ReturnUrlsSchema)
destination_wallet_idstring

The ID of the wallet to which the payment will be sent

Example: "wlt_7uAd21uizm5p1psa"
metadataobject

Additional metadata for the payment

Example: {"order_id":"1234","customer_id":"5678"}
payment_status_codestring

The status of the payment request. This will always be "Created" for a newly created payment request.

Example: "CREATED"
payment_method_codestring

The payment method used for the payment

Example: "card"
test_modeboolean

If the payment is a test payment for sandbox testing

Example: false
breakdownobject(PaymentBreakdownSchema)
refundobject(RefundPaymentResponseSchema)
billing_addressobject(BillingDetailsSchema)
payment_configobject(PaymentConfigSchema)
created_atstring(date-time)

The date and time the payment request was created

Example: "2021-01-01T12:00:00Z"
updated_atstring(date-time)

The date and time the payment request was last updated

Example: "2021-01-01T12:00:00Z"
expires_atstring(date-time)

The time after which the payment request will expire

Example: "2022-01-01T12:00:00Z"
completed_atstring(date-time)

The time at which the payment was completed

Example: "2022-01-01T12:00:00Z"
Response
application/json
{
  "id": "pay_7uAd21uizm5p1psa",
  "amount": 1099,
  "currency": "EUR",
  "description": "Payment for order #1234",
  "checkout_url": "https://checkout.helixpay.io/pay_7uAd21uizm5p1psa",
  "return_urls": {
    "success": "https://example.com/payment/success",
    "failure": "https://example.com/payment/failure"
  },
  "destination_wallet_id": "wlt_7uAd21uizm5p1psa",
  "metadata": {
    "order_id": "1234",
    "customer_id": "5678"
  },
  "payment_status_code": "CREATED",
  "payment_method_code": "card",
  "test_mode": false,
  "breakdown": {
    "fees": 0,
    "net_amount": 0
  },
  "refund": {
    "id": "rfd_123",
    "payment_id": "pay_123",
    "amount": 1000,
    "reason_code": "DUPLICATE",
    "other_reason": "Cancellation",
    "created_at": "2021-01-01T00:00:00Z",
    "status": "REFUND_REQUESTED",
    "updated_at": "2021-01-01T00:00:00Z"
  },
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "string",
    "phone_number": "string",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 101",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94107",
    "country_code": "US"
  },
  "payment_config": {
    "collected_fields": "email,phone_number"
  },
  "created_at": "2021-01-01T12:00:00Z",
  "updated_at": "2021-01-01T12:00:00Z",
  "expires_at": "2022-01-01T12:00:00Z",
  "completed_at": "2022-01-01T12:00:00Z"
}

Cancel a payment

Request

Cancel a specific payment. You can only cancel payments that are in the CREATED status.

Security
ApiKeyAuth
Path
payment_idstringrequired

The unique identifier for the payment

Example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Bodyapplication/jsonrequired
cancel_reasonstring

The reason for cancelling the payment

Example: "ABANDONED"
curl -i -X POST \
  https://docs.helix-pay.net/_mock/apis/external.gen/payments/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/cancel \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "cancel_reason": "ABANDONED"
  }'

Responses

Payment cancelled successfully

Bodyapplication/json
idstring

The unique identifier for the payment

Example: "pay_7uAd21uizm5p1psa"
amountinteger

The payment amount in the lowest currency unit (e.g. cents)

Example: 1099
currencystring

The payment currency

Example: "EUR"
descriptionstring

A short description of the payment

Example: "Payment for order #1234"
checkout_urlstring

The URL to redirect the user to for payment

Example: "https://checkout.helixpay.io/pay_7uAd21uizm5p1psa"
return_urlsobject(ReturnUrlsSchema)
destination_wallet_idstring

The ID of the wallet to which the payment will be sent

Example: "wlt_7uAd21uizm5p1psa"
metadataobject

Additional metadata for the payment

Example: {"order_id":"1234","customer_id":"5678"}
payment_status_codestring

The status of the payment request. This will always be "Created" for a newly created payment request.

Example: "CREATED"
payment_method_codestring

The payment method used for the payment

Example: "card"
test_modeboolean

If the payment is a test payment for sandbox testing

Example: false
breakdownobject(PaymentBreakdownSchema)
refundobject(RefundPaymentResponseSchema)
billing_addressobject(BillingDetailsSchema)
payment_configobject(PaymentConfigSchema)
created_atstring(date-time)

The date and time the payment request was created

Example: "2021-01-01T12:00:00Z"
updated_atstring(date-time)

The date and time the payment request was last updated

Example: "2021-01-01T12:00:00Z"
expires_atstring(date-time)

The time after which the payment request will expire

Example: "2022-01-01T12:00:00Z"
completed_atstring(date-time)

The time at which the payment was completed

Example: "2022-01-01T12:00:00Z"
Response
application/json
{
  "id": "pay_7uAd21uizm5p1psa",
  "amount": 1099,
  "currency": "EUR",
  "description": "Payment for order #1234",
  "checkout_url": "https://checkout.helixpay.io/pay_7uAd21uizm5p1psa",
  "return_urls": {
    "success": "https://example.com/payment/success",
    "failure": "https://example.com/payment/failure"
  },
  "destination_wallet_id": "wlt_7uAd21uizm5p1psa",
  "metadata": {
    "order_id": "1234",
    "customer_id": "5678"
  },
  "payment_status_code": "CREATED",
  "payment_method_code": "card",
  "test_mode": false,
  "breakdown": {
    "fees": 0,
    "net_amount": 0
  },
  "refund": {
    "id": "rfd_123",
    "payment_id": "pay_123",
    "amount": 1000,
    "reason_code": "DUPLICATE",
    "other_reason": "Cancellation",
    "created_at": "2021-01-01T00:00:00Z",
    "status": "REFUND_REQUESTED",
    "updated_at": "2021-01-01T00:00:00Z"
  },
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "string",
    "phone_number": "string",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 101",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94107",
    "country_code": "US"
  },
  "payment_config": {
    "collected_fields": "email,phone_number"
  },
  "created_at": "2021-01-01T12:00:00Z",
  "updated_at": "2021-01-01T12:00:00Z",
  "expires_at": "2022-01-01T12:00:00Z",
  "completed_at": "2022-01-01T12:00:00Z"
}

Consumers

Operations related to consumers. Consumers are mostly used in marketplace-type applications where they can deposit money in their account to pay for other goods or services or payout to their bank accounts.

Operations

Wallets

Operations related to wallets. Wallets are used to store funds for consumers.

Operations

Banks

Operations related to bank accounts. Bank accounts are used to withdraw funds from wallets.

Operations

Payouts

Operations related to payouts. Payouts are used to withdraw funds from wallets to bank accounts.

Operations

Integrations

Operations related to integrations. Integrations are used to connect Helix Pay with external systems (e.g. WIX).

Operations

Customers

Operations related to customers. Customers are the end-users who make payments. Not to be confused with consumers.

Operations

Balances

Operations related to account balances.

Operations

Sub-Merchants

Operations related to sub-merchants management. Allows parent merchants to manage their sub-merchants and create payments on their behalf, while also viewing volume analytics and current balances.

Operations

Health check endpoint

Request

A simple endpoint to check the health of the API

Security
ApiKeyAuth
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/health \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
messagestringrequired
Response
application/json
{
  "message": "string"
}
Copyright © Helix-Pay LTD. No rights reserved.