Skip to main content
While our dashboard is under development, the same steps can be performed using the endpoints available in the API reference.
1

Create a Sandbox Account

Get started with Paylias by heading over to sandbox.paylias.xyz. Create your free account. Note that Paylias will send you a unique code to the email you used to create the account. This code will be used to verify your account once its created.
2

Create a Namespace

Once logged in, you’ll be shown a page of all of your Namespaces. Since you may not have any right now, go ahead and click on the ‘Create namespace’ button and choose a name and domain. Note that domains cannot be edited once created.

A Namespace is a logical grouping of all other relevant API resources like Customers, Api Keys Payments etc. For instance if your company is called Oyster and you want your issued aliases to look like customer_name@oyster, the name you select can be Oyster but the domain should be oyster.
3

Create an API Key

After creating your Namespace, click on the “API Keys” tab on the sub menu bar and generate a new API key. API keys can be scoped by permission and restricted to access only certain resources. You can create multiple API keys with different permissions but please make sure to keep the keys in a secure environment. In case you think your keys have been compromised, you can immediately revoke access from our dashboard and generate a new key. For now, on your sandbox account, go ahead and create a new API Key and grant it all permissions.
4

Issue an Alias

We don’t offer an official SDK just yet, but you can generate one using our OpenAPI spec. Tools like Swagger Codegen or OpenAPI Generator make it easy to scaffold a client in your language of choice.
To issue your first credential, you can create a Customer object that represents a user or business in your system. Head over the Create Customer endpoint, fill in the details and issue your first alias. The Org-ID is the unique identifier for your organization and the Partner-ID is the unique identifier for the namspace you just created. Both can be copied from the dashboard.

If you prefer to use the command line, you can run this request but make sure to replace the values in the header with your own.
Issue an Alias
curl --request POST \
 --url https://sandbox.paylias.xyz/gateway/api/v1/csp/customer \
 --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 '
  {
    "first_name": "Ziyad",
    "last_name": "Parekh",
    "middle_name": "",
    "nick_name": "ziyad",
    "payment_address": "ziyad@oyster",
    "status": "ENABLED"
  }
  '
5

Subscribe to webhook events

Before requesting a payment, you must create webhook subscriptions to be notified of events as and when they take place during the payment lifecycle. While all events are required to be acknowledged at the very least, some events require follow up action from your side.

To create a webhook subscription, head over to the dashboard and click on the “Webhooks” tab on the sub menu and create a new Webhook.
  • Webhooks require you to pass in a valid endpoint that lives on your server. Please note that all endpoints must be https (SSL enabled).
  • Along with an endpoint, you must also subscribe to at least one event. For now, you may subscribe to all events but in production you can choose to segregate events per endpoint for better management.
  • If you would like Paylias to sign webhooks (recommended), you can optionally pass in a secret key which will be used to sign the generated payload. The signature will be included under the X-PAYLIAS-SIGNATURE header when the event is POSTed to your server.
Make sure you implement this endpoint on your server and return a response with a 200 HTTP status code.
6

Initiate your first payment

Paylias supports both Push and Pull payments but in this example we will initiate a Pull payment. A pull payment essentially is a payment request - your customer is initiating a request for payment from a customer on another platform (similar to an ecommerce payment).

Payments need to be created before they are submitted to the network. Just like in the previous step where you issued you first alias, you can head over to the Create Payment endpoint, update the <API Key>, <Org-ID>, <Partner-ID> and <Idempotency-Key> parameters below with your own identifiers and send the request. Alternatively, if you prefer to use the command line, run this code snippet in your terminal but make sure to replace the values in the header with your own.
Create a payment
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": {
      "billing": {
        "country": "US"
      },
      "payment_address": "ziyad@oyster",
      "first_name": "Ziyad",
      "last_name": "Parekh",
      "email": "ziyad.parekh@gmail.com",
      "phone": "+923008277879",
      "type": "Payee_Individual"
    },
    "debtor_party": {
      "billing": {
        "country": "US"
      },
      "payment_address": "jane@paylias",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@paylias.com",
      "phone": "+1987654321",
      "type": "Payer_Individual"
    },
    "payment_type": "Type_Pull",
    "reference": "INV001"
  }
In response you should get back the following confirmation
{
  "ok": true,
  "data": {
    "payment_id": "cjes76vsemvj3obsnc52",
    "amount": {
      "currency": "USD",
      "total": "10000"
    },
    "beneficiary_party": {
      "payment_address": "ziyad@oyster",
      "first_name": "Ziyad",
      "last_name": "Parekh",
      "email": "ziyad.parekh@gmail.com",
      "phone": "+923008277879",
      "type": "Payee_Individual",
      "billing": {
        "country": "US"
      }
    },
    "debtor_party": {
      "payment_address": "jane@paylias",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@paylias.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",
    "reference": "INV001",
    "payment_type": "Type_Pull"
  }
}
A few important things to note:
  • The payment_id should be a unique ID generated by your system. This will be used as the main identifier to trace payments throughout its lifecycle.
  • Currently, only USD is supported and all amounts must be submitted in their lowest denomination. In this example a payment of $100.00 is being requested.
  • Since this is a pull payment ("payment_type": "Type_Pull"), your customer is the beneficiary_party and their customer will be the debtor_party. This will reverse in the case of a push payment.
  • To make integration faster, we recommend using these credentials for the debtor_party since they will be routed to our simulator for a faster feedback loop. Otherwise, you will have to find other participants who are also integrating and request aliases they have configured on their end. More information about simulating payments can be found in our Simulator guide.
7

Submit the payment

Using the same payment_id used above, submit the payment to the network. You can head over to the Create Payment Submission endpoint, update the <API Key>, <Org-ID>, <Partner-ID> and <Idempotency-Key> parameters below with your own identifiers and send the request.

Alternatively, if you prefer to use the command line, run this code snippet in your terminal but make sure to replace the values in the header with your own.
Submit payment
curl --request POST \
    --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments/{payment_id}/submissions \
    --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>' \
In response you should get back the following confirmation
Response
{
  "ok": true,
  "data": {
    "payment_id": "cjes76vsemvj3obsnc53",
    "status": 1,
    "submission_time": 1743273405,
    "token": "sub_cvk3rfc20or8munut3tg",
    "relationships": {
      "payment": {
        "amount": {
          "currency": "USD",
          "total": "10000"
        },
        "beneficiary_party": {
          "billing": {
            "country": "US"
          },
          "email": "ziyad.parekh@gmail.com",
          "first_name": "Ziyad",
          "last_name": "Parekh",
          "payment_address": "ziyad@oyster",
          "phone": "+923008277879",
          "type": "Payee_Individual"
        },
        "debtor_party": {
          "payment_address": "jane@paylias",
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane@paylias.com",
          "phone": "+1987654321",
          "type": "Payer_Individual",
          "billing": {
            "country": "US"
          }
        },
        "device": {},
        "expires_at": 1743276991,
        "initiated_at": 1743273391,
        "location": {},
        "payment_id": "cjes76vsemvj3obsnc53",
        "reference": "INV0001"
      }
    }
  }
}
8

Monitor webhooks

After submitting your payment, monitor your webhook logs to be notified as the payment travels through the network to the correct participant, its customer and finally, back to you.Once the payment has been confirmed, a Transaction is created both, yours and your debitor’s, systems are notified and the payment is marked as completed.
Congratulations! You’ve just requested and received confirmation of your first payment. You can now reference subsequent guides to gain a deeper understanding of the various concepts we support along with how settlement works.
⌘I