Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.paylias.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Payment Admission Tasks are actions assigned to a partner in response to a Payment Admission, typically as part of a pull payment scenario. They enable you to authenticate an incoming payment request with your customer before finalizing the transaction. This serves as an important checkpoint—particularly in e-commerce use cases—where funds are being requested from your customer. Payment Admission Tasks give your platform the opportunity to present the payment request to the user and require explicit approval or rejection.

​
Purpose and Workflow

When your platform receives a Payment Admission Task, you are expected to process it by:
  • Authenticating the request with your customer using your preferred mechanism (e.g., biometric, OTP, PIN)
  • Accepting or rejecting the task based on your customer’s response or internal checks
Once accepted, the task is considered complete and Paylias proceeds to create the transaction. If rejected, the payment is not processed and no funds are moved.

​
Common Use Case: Pull Payments

In pull payment scenarios—such as when a merchant requests a payment from a customer—the customer’s financial platform receives an Admission Task. Example:
Customer adds items to their cart, enters their Paylias, and the merchant’s partner submits a pull payment. Paylias creates a Payment Admission and assigns an Admission Task to the customer’s platform. The platform must now authenticate and confirm the request with the customer.

​
Reason Codes

When rejecting a task, one of the following status_reason values should be used:
Reason CodeDescription
acceptedCustomer accepted the request
invalid_beneficiary_detailsBeneficiary info was invalid
alias_not_provisionedAlias exists but is not active
unknown_aliasAlias is unrecognized
account_closedCustomer account is closed
duplicate_paymentDetected as a duplicate
blocked_accountCustomer is blocked
currency_mismatchCurrency not supported
business_reasonsRejected due to internal policies
deceased_account_holderAccount holder is deceased
insufficient_fundsNot enough balance
unknown_errorGeneric system error
fraud_detectedTriggered fraud alert
regulatory_issuesRejected due to compliance policies
account_unavailableAccount temporarily inaccessible

​
Webhook Integration

To receive tasks in real-time, subscribe to the following webhook events:
  • payment_admission_task:created
  • payment_admission_task:updated

​
Respond to an Admission Task

Complete an admission task
curl --request PUT \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments/{payment_id}/admissions/{admission_id}/tasks/{task_id} \
     --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 '
    {
      "status": "completed",
      "status_reason": "accepted"
    }'
Reject an admission task
curl --request PUT \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments/{payment_id}/admissions/{admission_id}/tasks/{task_id} \
     --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 '
    {
      "status": "failed",
      "status_reason": "insufficient_funds"
    }'

​
Response

{
  "ok": true,
  "data": {
    "admission_id": "pay_adm_cvk3rfk20or8munut3v0",
    "assignee": 1,
    "status": 1,
    "status_reason": 1,
    "created_on": 1743273406,
    "modified_on": 1743273406,
    "name": "customer_authentication",
    "organization_id": "org_ct239n420or249k5bo90",
    "partner_id": "part_ct23b6420or249k5boag",
    "payment_id": "cjes76vsemvj3obsnc53",
    "token": "pat_cvk3rfk20or8munut400",
    "workflow": "customer_authentication"
  }
}

​
Fetch a Task by ID

Fetch
curl --request GET \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments/{payment_id}/admissions/{admission_id}/tasks/{task_id} \
     --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>'