Banks API

Warning: As a third party connected to nearpay APIs, upon usage, you agree to uphold the upmost security standards in accessing and using these APIs. These APIs share information that is confidential to you as a third party connected to nearpay. This information must be stored and used in a secure manner.

Authentication

NearPay uses API key as an authentication method. The API key must be included in every request as an api-key header.

Your bank API key can be retrieved from your NearPay dashboard. The api-key is required in all requests as a header. Please follow this path to get your API key: NearPay Dashboard -> Credentials -> Copy the api key.

Base URL

https://sandbox-api.nearpay.io/v1/banks-sdk/

Pagination

Please find the guide here in how to use pagination.

SDK Terminals

Terminals registered via the NearPay mobile SDK.

GET/banks-sdk/terminals

List Terminals

Request

GET
/banks-sdk/terminals
{}

Response 200

{
    "terminals": [
        {
            "id": "a1b2c3d4-0001-4000-8000-000000000001",
            "system_trace_audit_number": "000123",
            "card_acceptor_terminal_id": "10000001",
            "card_acceptor_id_code": "550100105798",
            "acquirer_institution_identification_code": "588888",
            "trsm": "FF1BCA",
            "client_id": "f5b80833-d1a6-414a-be4c-9f5ae3a9eaca",
            "created_at": "2024-01-15T10:00:00.000Z",
            "is_pulled_out": false,
            "pulled_out_at": null,
            "app_version": "3.5.0",
            "sdk_version": "2.1.0",
            "store": null
        }
    ],
    "pages": {
        "total": 1,
        "current": 1
    },
    "total": 10
}
GET/banks-sdk/terminals/{id}

Find Terminal

Request

GET
/banks-sdk/terminals/{id}
{}

{
    "terminal": {
        "id": "a1b2c3d4-0001-4000-8000-000000000001",
        "system_trace_audit_number": "000123",
        "card_acceptor_terminal_id": "10000001",
        "card_acceptor_id_code": "550100105798",
        "trsm": "FF1BCA",
        "is_pulled_out": false,
        "pulled_out_at": null,
        "package_name": "io.nearpay.app",
        "app_version": "3.5.0",
        "sdk_version": "2.1.0",
        "created_at": "2024-01-15T10:00:00.000Z",
        "updated_at": "2024-01-15T10:00:00.000Z"
    }
}

SDK Transactions

Transactions performed through the NearPay mobile SDK.

GET/banks-sdk/transactions

List Transactions

Request

GET
/banks-sdk/transactions
{}

Response 200

{
    "transactions": [
        {
            "id": "f2190ab9-3048-4364-a6f7-ce3ce53a3b16",
            "amount": "0.01",
            "is_approved": true,
            "is_reversed": false,
            "tid": "1881001155119328",
            "transaction_type": "00",
            "receipts": [
                {
                    "id": "519a01ef-7c01-4a79-9b60-bc69a7cb2158",
                    "qr_code": "https://api.nearpay.io/ui/receipt/519a01ef-7c01-4a79-9b60-bc69a7cb2158"
                }
            ],
            "reconciliation_id": null,
            "scheme": "P1",
            "created_at": "2024-01-15T10:05:00.000Z"
        }
    ],
    "pages": {
        "total": 5,
        "current": 1
    },
    "total": 50
}
GET/banks-sdk/transactions/{id}

Find Transaction

Request

GET
/banks-sdk/transactions/{id}
{}

{
    "transaction": {
        "id": "f2190ab9-3048-4364-a6f7-ce3ce53a3b16",
        "amount": "0.01",
        "is_approved": true,
        "is_reversed": false,
        "is_reconcilied": false,
        "tid": "1881001155119328",
        "transaction_type": "00",
        "scheme": "P1",
        "created_at": "2024-01-15T10:05:00.000Z",
        "receipts": [
            {
                "id": "519a01ef-7c01-4a79-9b60-bc69a7cb2158",
                "type": "purchase",
                "amount_authorized": {
                    "label": {
                        "arabic": "مبلغ الشراء",
                        "english": "PURCHASE AMOUNT"
                    },
                    "value": "0.01"
                },
                "is_approved": true,
                "is_reversed": false,
                "card_scheme": {
                    "name": {
                        "english": "mada",
                        "arabic": "مدى"
                    },
                    "id": "P1"
                },
                "qr_code": "https://api.nearpay.io/ui/receipt/519a01ef-7c01-4a79-9b60-bc69a7cb2158",
                "created_at": "2024-01-15T10:05:00.000Z"
            }
        ],
        "reconciliation_id": null
    }
}

SDK Reconciliations

Reconciliations for mobile SDK terminals.

GET/banks-sdk/reconciliations

List Reconciliations

Request

GET
/banks-sdk/reconciliations
{}

Response 200

{
    "reconciliations": [
        {
            "id": "b3c4d5e6-0002-4000-8000-000000000002",
            "stan": "000456",
            "total": 5,
            "currency": "682",
            "terminal_id": "a1b2c3d4-0001-4000-8000-000000000001",
            "total_value": "10.50",
            "time": "14:30:00",
            "is_balanced": true,
            "terminal": {
                "id": "a1b2c3d4-0001-4000-8000-000000000001",
                "tid": "1881001155119328",
                "name": "Terminal 01"
            },
            "created_at": "2024-01-15T14:30:00.000Z"
        }
    ],
    "pages": {
        "total": 2,
        "current": 1
    },
    "total": 15
}
GET/banks-sdk/reconciliations/{id}

Find Reconciliation

Request

GET
/banks-sdk/reconciliations/{id}
{}

{
    "reconciliation": {
        "id": "b3c4d5e6-0002-4000-8000-000000000002",
        "date": "15/01/2024",
        "time": "14:30:00",
        "start_date": "15/01/2024",
        "start_time": "08:00:00",
        "end_date": "15/01/2024",
        "end_time": "14:30:00",
        "card_acceptor_terminal_id": "10000001",
        "pos_software_version_number": "3.5.0",
        "card_scheme_sponsor_id": "BSFB",
        "is_balanced": true,
        "details": [],
        "schemes": [
            {
                "id": "P1",
                "name": {
                    "english": "mada",
                    "arabic": "مدى"
                },
                "count": 5,
                "total": "10.50"
            }
        ],
        "currency": "682",
        "system_trace_audit_number": "000456",
        "created_at": "2024-01-15T14:30:00.000Z",
        "updated_at": "2024-01-15T14:30:00.000Z",
        "qr_code": "https://api.nearpay.io/ui/reconciliation/b3c4d5e6-0002-4000-8000-000000000002",
        "device": null,
        "terminal": {
            "id": "a1b2c3d4-0001-4000-8000-000000000001",
            "os_type": "android",
            "reference_terminal_id": "REF001",
            "tid": "1881001155119328",
            "name": "Terminal 01",
            "auto_reconcile": false,
            "pulled_out_at": null,
            "created_at": "2024-01-15T10:00:00.000Z",
            "updated_at": "2024-01-15T10:00:00.000Z",
            "mode": "live",
            "trsm": "FF1BCA",
            "is_assigned": true,
            "is_connected": true
        }
    }
}

POS Terminals

Hardware POS terminals communicating via the NSP protocol.

GET/banks-sdk/pos/terminals

List POS Terminals

Request

GET
/banks-sdk/pos/terminals
{}

Response 200

{
    "terminals": [
        {
            "id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
            "card_acceptor_terminal_id": "10000001",
            "card_acceptor_id": "111111111111",
            "trsm": "FF1BCA",
            "acquirer_institution_identification_code": "588888",
            "created_at": "2024-01-15T10:00:00.000Z",
            "updated_at": "2024-01-15T10:00:00.000Z"
        }
    ],
    "pages": {
        "current": 1
    }
}
GET/banks-sdk/pos/terminals/{uuid}

Find POS Terminal

Request

GET
/banks-sdk/pos/terminals/{uuid}
{}

{
    "terminal": {
        "id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
        "card_acceptor_terminal_id": "10000001",
        "card_acceptor_id": "111111111111",
        "trsm": "FF1BCA",
        "acquirer_institution_identification_code": "588888",
        "created_at": "2024-01-15T10:00:00.000Z",
        "updated_at": "2024-01-15T10:00:00.000Z",
        "device": {
            "id": "c3ed2df1-ede2-402d-87d1-f0b59850f537",
            "vendor_id": "02",
            "serial_number": "SN000001"
        }
    }
}

POS Transactions

Transactions performed through hardware POS terminals.

GET/banks-sdk/pos/transactions

List POS Transactions

Request

GET
/banks-sdk/pos/transactions
{}

Response 200

{
    "transactions": [
        {
            "id": "d4e5f6a7-0003-4000-8000-000000000003",
            "is_approved": true,
            "is_reversed": false,
            "is_reversal_approved": false,
            "approval_code": "123456",
            "card_scheme": "P1",
            "action_code": "000",
            "amount_authorized": "100",
            "currency_code": "682",
            "performance": null,
            "system_trace_audit_number": "000789",
            "retrival_reference_number": "400123000000",
            "terminal": {
                "id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
                "card_acceptor_terminal_id": "10000001",
                "card_acceptor_id": "111111111111"
            },
            "lat": "24.7136",
            "lon": "46.6753",
            "region": "Riyadh",
            "created_at": "2024-01-15T10:05:00.000Z",
            "updated_at": "2024-01-15T10:05:00.000Z"
        }
    ],
    "pages": {
        "current": 1
    }
}
GET/banks-sdk/pos/transactions/{uuid}

Find POS Transaction

Request

GET
/banks-sdk/pos/transactions/{uuid}
{}

{
    "transaction": {
        "id": "d4e5f6a7-0003-4000-8000-000000000003",
        "transaction_type": "00",
        "amount_authorized": "100",
        "currency_code": "682",
        "system_trace_audit_number": "000789",
        "retrival_reference_number": "400123000000",
        "terminal": {
            "id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
            "trsm": "FF1BCA",
            "card_acceptor_id": "111111111111",
            "card_acceptor_terminal_id": "10000001",
            "acquirer_institution_identification_code": "588888"
        },
        "receipts": [
            {
                "id": "519a01ef-7c01-4a79-9b60-bc69a7cb2158",
                "type": "purchase",
                "is_approved": true,
                "approval_code": "123456",
                "card_scheme": {
                    "name": {
                        "english": "mada",
                        "arabic": "مدى"
                    },
                    "id": "P1"
                },
                "amount_authorized": {
                    "label": {
                        "arabic": "مبلغ الشراء",
                        "english": "PURCHASE AMOUNT"
                    },
                    "value": "1.00"
                },
                "qr_code": "https://api.nearpay.io/ui/receipt/519a01ef-7c01-4a79-9b60-bc69a7cb2158",
                "created_at": "2024-01-15T10:05:00.000Z"
            }
        ],
        "messages": [],
        "created_at": "2024-01-15T10:05:00.000Z",
        "updated_at": "2024-01-15T10:05:00.000Z"
    }
}

POS Reconciliations

Reconciliations for hardware POS terminals.

GET/banks-sdk/pos/reconciliations

List POS Reconciliations

Request

GET
/banks-sdk/pos/reconciliations
{}

Response 200

{
    "reconciliations": [
        {
            "id": "c5d6e7f8-0004-4000-8000-000000000004",
            "pos_totals": {
                "purchase": { "count": 5, "amount": "500" },
                "refund": { "count": 0, "amount": "0" }
            },
            "host_totals": {
                "purchase": { "count": 5, "amount": "500" },
                "refund": { "count": 0, "amount": "0" }
            },
            "terminal": {
                "id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
                "card_acceptor_terminal_id": "10000001",
                "card_acceptor_id": "111111111111"
            },
            "created_at": "2024-01-15T14:30:00.000Z",
            "updated_at": "2024-01-15T14:30:00.000Z"
        }
    ],
    "pages": {
        "current": 1
    }
}
GET/banks-sdk/pos/reconciliations/{uuid}

Find POS Reconciliation

Request

GET
/banks-sdk/pos/reconciliations/{uuid}
{}

{
    "reconciliation": {
        "id": "c5d6e7f8-0004-4000-8000-000000000004",
        "pos_totals": {
            "purchase": { "count": 5, "amount": "500" },
            "refund": { "count": 0, "amount": "0" }
        },
        "host_totals": {
            "purchase": { "count": 5, "amount": "500" },
            "refund": { "count": 0, "amount": "0" }
        },
        "terminal": {
            "id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
            "card_acceptor_terminal_id": "10000001",
            "card_acceptor_id": "111111111111",
            "trsm": "FF1BCA",
            "acquirer_institution_identification_code": "588888"
        },
        "receipt": {
            "id": "519a01ef-7c01-4a79-9b60-bc69a7cb2158",
            "qr_code": "https://api.nearpay.io/ui/reconciliation/c5d6e7f8-0004-4000-8000-000000000004"
        },
        "created_at": "2024-01-15T14:30:00.000Z",
        "updated_at": "2024-01-15T14:30:00.000Z"
    }
}