# Payments API

#### POST /payment-intents

Creates a payment intent for USDC disbursement from a lender's smart contract to a borrower's wallet. This step does not execute the transfer — it stages it and returns the parameters required for the on-chain ERC-20 approval.

http

```http
POST /payment-intents
Authorization: Bearer sk_live_xxxx
Content-Type: application/json

{
  "user_id": "usr_01J2K...",
  "amount_usd": 3000.00,
  "token": "USDC",
  "network": "polygon",
  "recipient_wallet": "0xUser5678...EfGh",
  "metadata": {
    "loan_id": "loan_ext_123",
    "product": "personal_loan",
    "term_months": 12
  }
}
```

**Response**

json

```json
{
  "payment_intent": {
    "id": "pi_6QsN...",
    "status": "pending_approval",
    "user_id": "usr_01J2K...",
    "amount_usd": 3000.00,
    "token": "USDC",
    "network": "polygon",
    "recipient_wallet": "0xUser5678...EfGh",
    "contract_address": "0xRupiDisbursement...0001",
    "approval_calldata": {
      "function": "approve",
      "spender": "0xRupiDisbursement...0001",
      "amount": "3000000000",
      "token_contract": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
    },
    "expires_at": "2024-12-01T10:30:00Z",
    "created_at": "2024-12-01T10:00:00Z"
  }
}
```

The `approval_calldata` contains the parameters needed by the client to call `approve()` on the USDC contract, authorizing the Rupi disbursement contract to pull the funds. Once the approval transaction is confirmed on-chain, the payment intent status automatically transitions to `approval_confirmed` and the disbursement can be executed.

#### POST /charges

Executes a confirmed payment intent. Requires the payment intent to be in `approval_confirmed` status.

http

```http
POST /charges
Authorization: Bearer sk_live_xxxx
Content-Type: application/json

{
  "payment_intent_id": "pi_6QsN...",
  "approval_tx_hash": "0x789abc..."
}
```

**Response**

json

```json
{
  "charge": {
    "id": "chg_3RkL...",
    "payment_intent_id": "pi_6QsN...",
    "status": "succeeded",
    "amount_usd": 3000.00,
    "token": "USDC",
    "network": "polygon",
    "disbursement_tx_hash": "0xcharge_txhash...",
    "recipient_wallet": "0xUser5678...EfGh",
    "executed_at": "2024-12-01T10:05:00Z"
  }
}
```

**ERC-20 approval flow**

```
Lender Backend
    │
    ├─► POST /payment-intents → returns approval_calldata
    │
    ▼
Client SDK / Lender Frontend
    │
    ├─► User calls approve(spender=RupiDisbursementContract, amount=X)
    │   on USDC token contract
    │
    └─► Approval tx confirmed on-chain
    │
    ▼
Rupi Webhook: payment_intent.approval_confirmed
    │
    ▼
Lender Backend
    │
    └─► POST /charges with approval_tx_hash
    │
    ▼
Rupi executes transferFrom() on USDC contract
    │
    ▼
Webhook: charge.succeeded + disbursement_tx_hash
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rupi.global/core-documentation/markdown/payments-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.