> ## 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 Task

> Learn how to use Payment Admission Tasks to perform custom validation on inbound payments.

**Payment Admission Tasks** are actions assigned to a partner in response to a [Payment Admission](/concepts/payments/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 Code                   | Description                         |
| ----------------------------- | ----------------------------------- |
| accepted                      | Customer accepted the request       |
| invalid\_beneficiary\_details | Beneficiary info was invalid        |
| alias\_not\_provisioned       | Alias exists but is not active      |
| unknown\_alias                | Alias is unrecognized               |
| account\_closed               | Customer account is closed          |
| duplicate\_payment            | Detected as a duplicate             |
| blocked\_account              | Customer is blocked                 |
| currency\_mismatch            | Currency not supported              |
| business\_reasons             | Rejected due to internal policies   |
| deceased\_account\_holder     | Account holder is deceased          |
| insufficient\_funds           | Not enough balance                  |
| unknown\_error                | Generic system error                |
| fraud\_detected               | Triggered fraud alert               |
| regulatory\_issues            | Rejected due to compliance policies |
| account\_unavailable          | Account 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

```bash Complete an admission task theme={null}
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"
    }'
```

```bash Reject an admission task theme={null}
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

```json theme={null}
{
  "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

```bash Fetch theme={null}
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>'
```