AccessPay

Market: UK

Business Capabilities

The AccessPay connector accepts payment instructions from upstream channels, validates accounts, stages payments into batches, and submits them to AccessPay for processing. It then polls for status, fetches pain.002 reports, maps results, and notifies downstream systems via webhooks.

Accepts payment instructions for standard CHAPS/SEPA/FPS payments and BACS direct payments.
Validates beneficiary and debtor accounts against AccessPay before staging.
Stages payment items and groups them into submissions on a configurable schedule.
Sends submissions to AccessPay using JWT-based OAuth, then polls for status.
Fetches pain.002 reports, maps results, and notifies downstream systems via webhooks.
Supports reprocessing of failed batches or individual payments.

Payment Products

Standard payments (CHAPS/SEPA/FPS): ingested through /accesspay/v1/payments.
Direct payments (BACS Credit): ingested through /accesspay/v1/direct-payments.
Account name verification (CoP): validated through /accesspay/v1/validate-account.

Exposed Endpoints

Submit payment batch: POST /accesspay/v1/payments - Stages one or more CHAPS/SEPA/FPS payments for batch submission.
Submit direct payment batch: POST /accesspay/v1/direct-payments - Stages one or more BACS Credit (direct) payments for batch submission.
Validate account: POST /accesspay/v1/validate-account - Performs Account Name Verification (CoP) for a given account number and sort code.
Get payment status: GET /accesspay/v1/payments/{id}/status - Returns the current processing status for a submitted payment batch.
Reprocess batch: POST /accesspay/v1/reprocess/batch/{batchId} - Restages a failed batch for resubmission.
Reprocess payment: POST /accesspay/v1/reprocess/payment/{paymentId} - Clones a failed payment instruction for the next batch window.

Vault Configuration

accesspayUrl - Base URL of the AccessPay API (e.g., https://api.live.services.accesspay.com).
accesspayKeyName - Vault key name for the RS256 private key used to sign JWT bearer assertions.
accesspayAuthConfig - JSON string for the OAuth2 auth configuration. Example:

Copy

{
                "grantType": "urn:ietf:params:oauth:grant-type:jwt-bearer",
                "issuer": "<client-id>@api.accesspay.com",
                "scope": "https://api.accesspay.com/auth/submissions.readonly https://api.accesspay.com/auth/payments.write https://api.accesspay.com/auth/payment-instructions.write",
                "uri": "/oauth2/v4/token"
        }

accesspayBatchCron - Quartz cron expression controlling when staged payments are grouped and submitted (default: 0 0 11,13,15,18 * * ? Europe/London).
accesspayStatusCron - Quartz cron expression controlling how often submitted batches are polled for status updates (default: 0 0/15 0-8,10,12,14,16-23 * * ? Europe/London).
accesspayArchiveCron - Quartz cron expression controlling when completed batches are archived (default: 0 0 2 * * ? Europe/London, nightly at 02:00).
accesspayStatusRequestDelay - Optional delay between consecutive status-poll calls, used to avoid throttling by AccessPay.
accesspayStatusMapping - JSON array that maps AccessPay submission statuses to the connector's internal tracking states. Example:

Copy

[
                { "paymentStatus": "Processing",       "internalStatus": "Pending" },
                { "paymentStatus": "Delivered",        "internalStatus": "Pending" },
                { "paymentStatus": "ApprovalRequired", "internalStatus": "Pending" },
                { "paymentStatus": "ReviewValidation", "internalStatus": "Pending" },
                { "paymentStatus": "ReviewDetect",     "internalStatus": "Pending" },
                { "paymentStatus": "GatewayAccepted",  "internalStatus": "Paid" },
                { "paymentStatus": "GatewayRejected",  "internalStatus": "Rejected" },
                { "paymentStatus": "ApprovalRejected", "internalStatus": "Rejected" },
                { "paymentStatus": "Cancelled",        "internalStatus": "Rejected" },
                { "paymentStatus": "Failed",           "internalStatus": "Rejected" }
        ]

reportsConfig - JSON object controlling report retrieval behavior. Example:

Copy

{
                "reportType": "pain002",
                "reportDelayHours": 1,
                "reportStatus": "RJCT, ACSC, PART"
        }

webhookConfig - JSON object containing the webhook endpoints where batch completion events are posted.

Scheduling

Three cron schedules control the connector's batch processing lifecycle:

accesspayBatchCron - Controls when staged payments are grouped and submitted to AccessPay. Pending items are grouped by the group field (for example, tenant or workflow), assigned a paymentInformationId if missing, and sent as a submission.
accesspayStatusCron - Controls status polling frequency. The connector polls /submissions/{id} for all pending submission IDs on each cycle.
accesspayArchiveCron - Controls when completed batches and their payments are archived and cleaned up.

Status Mapping

During each status-poll cycle, the connector fetches the current submission status from AccessPay and looks it up in the accesspayStatusMapping configuration. The internalStatus value drives one of four outcomes:

Pending: keep polling on the next cycle. The connector records the status history.
Paid: the connector fetches pain.002 reports, reconciles each payment ID against the expected set, maps the per-payment statuses, sends the completion webhook, and marks the batch complete. If reconciliation finds duplicate, missing, or additional payment IDs, the connector marks the batch Invalid instead, keeps the status record, and stops re-polling.
Rejected: the connector sends the rejection webhook immediately, without fetching a report, and sets every payment to Completed with providerStatus=Failed.
Unmapped: if the AccessPay status is not found in the mapping, automatic processing halts. The batch is left in an unresolved state until the configuration is updated.

Request Structures and Samples

POST /accesspay/v1/payments

Stages one or more CHAPS/SEPA/FPS payments for batch submission to AccessPay.

Headers:

Header	Required	Description
`Idempotency-Key`	No	UUID. If the same key is submitted twice, the second call returns `409 Conflict`.
`X-Webhook-Id`	No	Identifier for the webhook configuration entry to use on completion.

Request structure:

Copy

{
    "data": {
        "workflowId": "uuid",
        "transactionType": "CHAPS | SEPA | FPS",
        "batchBookingPreferred": "true | false",
        "debtorAccount": {
            "iban": "string",
            "bban": "string",
            "accountValidation": {
                "accountType": "Personal | Business",
                "accountNumber": "string",
                "name": "string",
                "sortCode": "string"
            }
        },
        "paymentInformationId": "string",
        "requestedExecutionDate": "YYYY-MM-DD",
        "payments": [
            {
                "endToEndIdentification": "string",
                "instructionIdentification": "string",
                "debtorName": "string",
                "debtorId": "string",
                "ultimateDebtor": "string",
                "instructedAmount": {
                    "currency": "string",
                    "amount": "string"
                },
                "creditorAccount": {
                    "iban": "string",
                    "bban": "string"
                },
                "creditorAgent": "string",
                "creditorAgentName": "string",
                "creditorName": "string",
                "creditorId": "string",
                "creditorAddress": {
                    "streetName": "string",
                    "buildingNumber": "string",
                    "townName": "string",
                    "postCode": "string",
                    "country": "string"
                },
                "ultimateCreditor": "string",
                "purposeCode": "string",
                "chargeBearer": "SLEV | CRED | DEBT | SHAR",
                "serviceLevel": "string",
                "remittanceInformationUnstructured": "string",
                "remittanceInformationStructured": {
                    "referenceType": "string",
                    "reference": "string",
                    "referenceIssuer": "string"
                }
            }
        ]
    },
    "context": {}
}

Sample request:

Copy

{
    "data": {
        "transactionType": "CHAPS",
        "batchBookingPreferred": "false",
        "debtorAccount": {
            "iban": "GB01BARC20000040757128",
            "bban": "20000040757128"
        },
        "paymentInformationId": "152F74A59714477DA3CCDC773BEF58E7",
        "requestedExecutionDate": "2025-05-26",
        "payments": [
            {
                "endToEndIdentification": "152F74A59714477DA3CCDC773BEF58E7",
                "instructionIdentification": "152F74A59714477DA3CCDC773BEF58E7",
                "debtorName": "ACME INDUSTRIES",
                "debtorId": "1234",
                "ultimateDebtor": "KARL DIGGLE",
                "instructedAmount": {
                    "currency": "GBP",
                    "amount": "12350"
                },
                "creditorAccount": {
                    "iban": "GB55BUKB20041555555555",
                    "bban": "20041555555555"
                },
                "creditorAgent": "BARCGB22",
                "creditorAgentName": "BARCLAYS",
                "creditorName": "SUPPLIER 111",
                "creditorId": "5678",
                "creditorAddress": {
                    "streetName": "City Tower",
                    "buildingNumber": "18",
                    "townName": "Manchester",
                    "postCode": "M1 4BT",
                    "country": "GB"
                },
                "ultimateCreditor": "RITA",
                "purposeCode": "SALA",
                "chargeBearer": "CRED",
                "serviceLevel": "SEPA",
                "remittanceInformationUnstructured": "Ref Number 111",
                "remittanceInformationStructured": {
                    "referenceType": "RTI",
                    "reference": "/456",
                    "referenceIssuer": "TEST"
                }
            }
        ],
        "workflowId": "cbbec24f-bf24-4145-bc48-6c5c2662a93e"
    }
}

Sample response:

Copy

{
    "id": "a3f7c1d2-5e89-4b01-9f23-7d4a6e8c0b12"
}

Sample response (with account validation failures):

Copy

{
    "id": "a3f7c1d2-5e89-4b01-9f23-7d4a6e8c0b12",
    "invalidAccounts": [
        {
            "matched": false,
            "reasonCode": "ANNM",
            "matchStrength": "NoMatch",
            "accountNumber": "GB55BUKB20041555555555"
        }
    ]
}

Error codes:

Code	Description
409	Conflict. A payment with this `Idempotency-Key` was already submitted.

POST /accesspay/v1/direct-payments

Stages one or more BACS Credit (direct) payments for batch submission.

Headers:

Header	Required	Description
`Idempotency-Key`	No	UUID. If the same key is submitted twice, the second call returns `409 Conflict`.
`X-Webhook-Id`	No	Identifier for the webhook configuration entry to use on completion.

Request structure:

Copy

{
    "data": {
        "workflowId": "uuid",
        "transactionType": "Credit",
        "serviceUserNumber": "string",
        "debtorName": "string",
        "debtorAccount": {
            "iban": "string",
            "bban": "string"
        },
        "requestedExecutionDate": "YYYY-MM-DD",
        "payments": [
            {
                "instructedAmount": {
                    "currency": "string",
                    "amount": "string"
                },
                "creditorAccount": {
                    "iban": "string",
                    "bban": "string"
                },
                "creditorName": "string",
                "purposeCode": "string",
                "remittanceInformationUnstructured": "string",
                "remittanceInformationStructured": {
                    "referenceType": "string",
                    "reference": "string"
                }
            }
        ]
    },
    "links": {
        "config": "uuid"
    },
    "context": {}
}

Sample request:

Copy

{
    "data": {
        "transactionType": "Credit",
        "serviceUserNumber": "100101",
        "debtorName": "ACME INDUSTRIES",
        "debtorAccount": {
            "iban": "GB01BARC20000040757128",
            "bban": "20000040757128"
        },
        "requestedExecutionDate": "2025-07-06",
        "payments": [
            {
                "instructedAmount": {
                    "currency": "GBP",
                    "amount": "1390.11"
                },
                "creditorAccount": {
                    "bban": "30995137816460"
                },
                "purposeCode": "99",
                "remittanceInformationStructured": {
                    "referenceType": "RTI",
                    "reference": "/456"
                }
            },
            {
                "instructedAmount": {
                    "currency": "GBP",
                    "amount": "1"
                },
                "creditorAccount": {
                    "iban": "GB55BUKB20041566666666",
                    "bban": "20041566666666"
                },
                "creditorName": "SUPPLIER 222",
                "purposeCode": "99",
                "remittanceInformationUnstructured": "Ref Number 222",
                "remittanceInformationStructured": {
                    "referenceType": "RTI",
                    "reference": "/678"
                }
            }
        ]
    },
    "links": {
        "config": "86d2fdeb-c1a9-4528-8da8-946856a11c03"
    }
}

Sample response:

Copy

{
    "id": "b7e2d4f1-3a56-4c89-8e01-2f5b9c7a4d63"
}

Error codes:

Code	Description
409	Conflict. A payment with this `Idempotency-Key` was already submitted.

POST /accesspay/v1/validate-account

Performs Account Name Verification (Confirmation of Payee) for a given account number and sort code.

Request structure:

Copy

{
    "accountType": "Personal | Business",
    "accountNumber": "string",
    "name": "string",
    "sortCode": "string",
    "identifier": "string"
}

Sample request:

Copy

{
    "accountType": "Personal",
    "accountNumber": "12345678",
    "name": "Jane Bloggs",
    "sortCode": "200000"
}

Sample response (matched):

Copy

{
    "matched": true,
    "matchStrength": "ExactMatch"
}

Sample response (not matched):

Copy

{
    "matched": false,
    "reasonCode": "ANNM",
    "matchStrength": "NoMatch"
}

Error codes:

Code	Description
400	Bad Request. Missing required fields.

GET /accesspay/v1/payments/{id}/status

Returns the current processing status for a submitted payment batch.

Path parameters:

Parameter	Type	Required	Description
`id`	UUID	Yes	Submission ID returned by `/payments` or `/direct-payments`.

Sample response:

Copy

{
    "paymentStatusReport": {
        "batchId": "8de12d87-e6ff-4ba4-bdbc-80974dd6aab4",
        "batchStatus": "GatewayAccepted",
        "internalStatus": "Paid",
        "internalStatusDetails": [],
        "payments": [
            { "id": "0058a970-f47a-4561-82cb-e0a8d4ee7232" },
            { "id": "05d87c68-bcfa-4b18-83e4-dbc37a59d8ea" }
        ]
    }
}

Webhook Notifications

Submission webhook (psrWebhook): sent right after AccessPay accepts a batch, containing submission metadata. Downstream systems use this to confirm that a batch was created (payments are still pending).
Status webhook (statusWebhook): sent after reports are parsed, carrying per-payment outcomes and provider reasons where present.

Downstream systems correlate webhook data using the stored X-Webhook-Id or group identifier and the returned payment or batch identifiers.

Exception Handling

Unmapped statuses: halted and highlighted (no silent retries) until configuration is updated.
Partial pain.002 reports: multi-part (PART) reports are merged before the completion notification is sent.
Reprocess flows: re-run a failed batch (POST /accesspay/v1/reprocess/batch/{batchId}) or a single payment (POST /accesspay/v1/reprocess/payment/{paymentId}). Restaged items are submitted on the next batch cycle or immediately, depending on the reprocess type.

Archiving

A nightly cron (accesspayArchiveCron) archives completed payments and batches once their lifecycle finishes. The connector moves completed standard and direct payments into a historical store partitioned by the month they were received, preserving the full payment payload, provider status, and status reasons. It removes completed batches after their payments are archived, and emits an audit event for each archive or cleanup operation.