# Payment intent

`GET /v2/payments/intents`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobpay.co.za`
- Production: `https://api.bobpay.co.za`

**Authentication:** Bearer token required. Obtain one via `POST /login` (see the Authentication page).

## Example request

```bash
curl -X GET "https://api.sandbox.bobpay.co.za/v2/payments/intents" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

This endpoint allows you to query and retrieve comprehensive information about payment intents across your accounts. With support for a variety of filters, you can refine your search to access specific payment details. This endpoint also provides an option to export the query results into a CSV file, facilitating further analysis and record-keeping.

#### Available parameters

| Key | Description | Type | Required |
| --- | --- | --- | --- |
| id | The ID of a payment intent. | integer | No |
| statuses | One or more of the following statuses, passed as a JSON array (e.g. `statuses=["paid","unpaid"]`): paid, unpaid, canceled, refunded, partially_refunded, refund_pending, failed, deleted, chargeback. | array of string | No |
| from_bank | The payer's bank. One of: standard-bank, fnb, nedbank, absa, capitec, investec, bank-zero, tyme-bank, discovery-bank, african-bank, old-mutual-bank. | string | No |
| recipient_account_id | Pass in the recipient_account_id to get payment intents received. | integer | No |
| account_id | Pass in account_id to get payment intents made. | integer | No |
| search | Case-insensitive partial match on payment references. | string | No |
| csv | Use true to export the results to a CSV file. The CSV is generated in the background and emailed to you. | boolean | No |
| start_date | Start date for the time period (format: YYYY-MM-DD HH:MM:SS). | string (date/time) | No |
| end_date | End date for the time period (format: YYYY-MM-DD HH:MM:SS). | string (date/time) | No |
| limit | Limit the number of records returned. | integer | No |
| offset | The number of records to skip (for pagination). | integer | No |
| order | ASC / DESC | string | No |
| order_by | Order by any field. | string | No |
| include_retained_date | If true, includes the date until which funds are retained (`retained_until`) in the results. | boolean | No |

#### Response example

```json
{
    "payment_intents": [
        {
            "id": 54370,
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "short_reference": "3WFFG",
            "from_bank": "fnb",
            "custom_payment_id": "265",
            "notify_url": "https://yourwebsite.co.za/webhook/payment-notification",
            "success_url": "https://yourwebsite.co.za/payment/success",
            "pending_url": "https://yourwebsite.co.za/payment/pending",
            "cancel_url": "https://yourwebsite.co.za/payment/cancelled",
            "item_name": "Order 1452",
            "item_description": "Lego Star Wars",
            "amount": 200,
            "paid_amount": 200,
            "total_paid_amount": 200,
            "signature": "1eb8d2109cb744f0b6a63f168a75ac8e",
            "time_created": "2024-06-12T11:14:07.16374+02:00",
            "account_id": 208,
            "account": {
                "id": 208,
                "name": "Auto-generated account",
                "account_code": "AUT002",
                "signup_name": "Sandbox User",
                "is_merchant": false
            },
            "account_code": null,
            "transacting_as_email": "customer@example.co.za",
            "status": "paid",
            "recipient_account_code": "",
            "recipient_account_id": 209,
            "recipient_account": {
                "id": 209,
                "name": "Bob Go",
                "account_code": "BOB001",
                "signup_name": "John Doe",
                "is_merchant": true
            },
            "email": "customer@example.co.za",
            "is_test": false,
            "payment_method": "credit-card",
            "original_requested_payment_method": "credit-card",
            "payment_id": 37499,
            "payment": {
                "id": 37499,
                "payment_method_id": 167,
                "payment_method": "credit-card",
                "amount": 200,
                "status": "success"
            }
        }
    ],
    "count": 1
}
```

---

#### Response fields

| Key | Description | Type |
| --- | --- | --- |
| payment_intents | Array of payment intent objects matching the query. | array |
| count | Total number of payment intents matching the query. | integer |

**Payment intent fields:**

| Key | Description | Type |
| --- | --- | --- |
| id | Unique identifier for the payment intent. | integer |
| uuid | Universally unique identifier for the payment intent. | string |
| short_reference | Short reference or code for easy tracking/display. | string |
| from_bank | The payer's bank, if known. | string |
| custom_payment_id | Custom identifier for the payment (business reconciliation). | string |
| notify_url | URL notified when the payment status changes. | string |
| success_url | Redirect URL for successful payment. | string |
| pending_url | Redirect URL for pending payment. | string |
| cancel_url | Redirect URL for cancelled payment. | string |
| item_name | Name of the item being purchased. | string |
| item_description | Description of the item. | string |
| amount | Amount of the payment intent. | float |
| paid_amount | Amount paid for this intent. | float |
| total_paid_amount | Total amount paid towards this intent. | float |
| signature | Signature for this intent. | string |
| time_created | Timestamp when the payment intent was created (ISO 8601 format). | string (datetime) |
| account_id | ID of the payer's account. | integer |
| account | The payer's account object (see below for nested fields). | object |
| account_code | Code of the payer's account (always null; see `account.account_code`). | string |
| transacting_as_email | The payer's email address (if acting on behalf of another). | string |
| status | Payment intent status (`paid`, `unpaid`, `canceled`, `refunded`, `partially_refunded`, `refund_pending`, `failed`, `deleted`, `chargeback`). | string |
| recipient_account_code | Code of the account receiving the payment (always empty; see `recipient_account.account_code`). | string |
| recipient_account_id | ID of the recipient (payee) account. | integer |
| recipient_account | The recipient's account object (see below for nested fields). | object |
| mobile_number | Payer's mobile number. | string |
| email | Payer's email address. | string |
| is_test | Whether this payment intent is a test transaction. | boolean |
| payment_method | The payment method used (e.g., credit-card, instant-eft). | string |
| original_requested_payment_method | The payment method originally requested when the intent was created. | string |
| payment_id | ID of the payment record associated with this intent. | integer |
| payment | Object containing payment transaction details (see below for nested fields). | object |
| retained_until | If the funds are retained, the date until which they are retained (only included when `include_retained_date=true`). | string (datetime) |

**account / recipient_account nested fields:**

| Key | Description | Type |
| --- | --- | --- |
| id | Account ID | integer |
| name | Account name | string |
| account_code | Unique code of the account | string |
| signup_name | Signup name for the account | string |
| is_merchant | Whether the account is a merchant | boolean |

**payment nested fields:**

| Key | Description | Type |
| --- | --- | --- |
| id | Unique identifier for the payment transaction. | integer |
| payment_method_id | Internal ID referencing the specific payment method used. | integer |
| payment_method | Name of the payment method used for the transaction. | string |
| amount | The amount processed in this payment transaction. | float |
| status | Status of the payment transaction (`success`, `pending`, `failed`, `cancelled`, `reversed`, `refunded`, `refund_pending`, `partially_refunded`, `chargeback`). | string |