Payment

All transactions on the Paylias network begin with a Payment. Whether you’re initiating a push or pull payment, the first step is to create a payment object that defines the intent and parties involved. A payment encapsulates key details such as the amount, payment type (push or pull), payer and payee aliases, and associated metadata like reference numbers and billing information. Once a payment is created, it can be acted upon through tasks — either a Submission Task (for push payments) or an Admission Task (for pull payments).

All amounts must be specified in the lowest denomination of the currency (e.g. cents for USD).

Payment APIs

Create a Payment

Create

curl --request POST \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>' \
     --header 'idempotency-key: <uuid>' \
     --data '
{
  "payment_id": "cjes76vsemvj3obsnc52",
  "amount": {
    "currency": "USD",
    "total": "10000"
  },
  "beneficiary_party": {
    "payment_address": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "type": "Payee_Individual",
    "billing": {
      "country": "US"
    }
  },
  "debtor_party": {
    "payment_address": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "phone": "+1987654321",
    "type": "Payer_Individual",
    "billing": {
      "country": "US"
    }
  },
  "reference": "INV001",
  "payment_type": "Type_Pull"
}
'

Response

{
  "ok": true,
  "data": {
    "amount": {
      "currency": "USD",
      "total": "10000"
    },
    "beneficiary_party": {
      "payment_address": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "type": "Payee_Individual",
      "billing": {
        "country": "US"
      }
    },
    "debtor_party": {
      "payment_address": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+1987654321",
      "type": "Payer_Individual",
      "billing": {
        "country": "US"
      }
    },
    "device": {},
    "location": {},
    "expires_at": "2023-08-13T08:55:04Z",
    "initiated_at": "2023-08-12T08:55:04Z",
    "organization_id": "org_d09gv1s20or2svojjmt0",
    "partner_id": "part_123456789",
    "payment_id": "pay_123456789",
    "reference": "INV001",
    "payment_type": "Type_Pull"
  }
}

Fetch a Payment

Use this endpoint to retrieve the details of a specific payment using its payment_id.

Find a payment

curl --request GET \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments/{payment_id} \
     --header 'accept: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>'

Response

{
  "ok": true,
  "data": {
    "amount": {
      "currency": "USD",
      "total": "10000"
    },
    "beneficiary_party": {
      "payment_address": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "type": "Payee_Individual",
      "billing": {
        "country": "US"
      }
    },
    "debtor_party": {
      "payment_address": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+1987654321",
      "type": "Payer_Individual",
      "billing": {
        "country": "US"
      }
    },
    "device": {},
    "location": {},
    "expires_at": "2023-08-13T08:55:04Z",
    "initiated_at": "2023-08-12T08:55:04Z",
    "organization_id": "org_d09gv1s20or2svojjmt0",
    "partner_id": "part_123456789",
    "payment_id": "pay_123456789",
    "reference": "INV001",
    "payment_type": "Type_Pull"
  }
}

Search Payments

You can search across your payment records using flexible filters such as payment_id, reference, alias fields, and pagination controls.

curl --request GET \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments \
     --header 'accept: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>'

Query Parameters

Parameter	Type	Description
`payment_id`	string	Filter by a specific Payment ID
`reference`	string	Filter by reference string (e.g. invoice ID)
`beneficiary_payment_address`	string	Filter by the payee’s alias
`debtor_payment_address`	string	Filter by the payer’s alias
`limit`	string	Maximum number of records per page
`page`	string	Page number for pagination
`direction`	string	Optional direction filter (if applicable)

Response

{
  "ok": true,
  "data": {
    "count": 1,
    "payments": [
      {
        "amount": {
          "currency": "USD",
          "total": "10000"
        },
        "beneficiary_party": {
          "payment_address": "john@example.com",
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "phone": "+1234567890",
          "type": "Payee_Individual",
          "billing": {
            "country": "US"
          }
        },
        "debtor_party": {
          "payment_address": "jane@example.com",
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane@example.com",
          "phone": "+1987654321",
          "type": "Payer_Individual",
          "billing": {
            "country": "US"
          }
        },
        "device": {},
        "location": {},
        "expires_at": "2023-08-13T08:55:04Z",
        "initiated_at": "2023-08-12T08:55:04Z",
        "organization_id": "org_d09gv1s20or2svojjmt0",
        "partner_id": "part_123456789",
        "payment_id": "pay_123456789",
        "reference": "INV001"
      }
    ]
  }
}

Getting started

Core Concepts

Guides

Settlement

Simulation

Payment APIs

Create a Payment

Response

Fetch a Payment

Response

Search Payments

Query Parameters

Response

​Payment APIs

​Create a Payment

​Response

​Fetch a Payment

​Response

​Search Payments

​Query Parameters

​Response

Payment APIs

Create a Payment

Response

Fetch a Payment

Response

Search Payments

Query Parameters

Response