### Authentication Response Examples

Source: https://docs.volt.io/api-reference/authentication/post-oauth

Examples of successful and failed JSON responses from the authentication endpoint.

```json
{
  "access_token": "eyJ0eXAiOi...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "50679c5db61d63b107273fa11a666a09fc7ae28"
}
```

```json
{
  "code": 401,
  "message": "Bad credentials, please verify your credentials are correctly set"
}
```

--------------------------------

### POST /payments Response Example

Source: https://docs.volt.io/implementation/payments/integration-guides/api-only-guide

This is an example of the response received after initiating a payment request via the POST /payments endpoint. It includes details about the payment initiation flow and a redirect URL.

```json
{
    //...
    "paymentInitiationFlow": {
        "status": "PROCESSING",
        "details": {
            "reason": "AWAITING_USER_REDIRECT",
            "redirect": {
                "url": "https://vo.lt/short",
                "directUrl": "https://myBank.com/authorisation?code=xyz"
            }
        }
    }
    //...
}
```

```json
{
    //...
    "paymentInitiationFlow": {
        "status": "PROCESSING",
        "details": {
            "reason": "AWAITING_USER_REDIRECT",
            "redirect": {
                "url": "https://vo.lt/short",
                "directUrl": "https://sca.volt.io/{paymentId}"
            }
        }
    }
    //...
}
```

--------------------------------

### Payout Request Body Examples

Source: https://docs.volt.io/implementation/volt-accounts/payouts/payouts-api

JSON request body examples for different currency types and beneficiary account structures.

```json
{
  "amount": 12345,
  "currency": "EUR",
  "paymentTitle": "SEPA test",
  "beneficiary": {
    "name": "John Johnson",
    "iban": "DE07500105176551562526"
  },
  "externalReference": "Some reference"
}
```

```json
{
  "amount": 12345,
  "currency": "GBP",
  "paymentTitle": "GBP test",
  "beneficiary": {
    "name": "John Johnson",
    "accountNumber": "12345678",
    "sortCode": "404777"
  },
  "externalReference": "Some reference"
}
```

```json
{
  "amount": 12345,
  "currency": "AUD",
  "paymentTitle": "AUD test",
  "beneficiary": {
    "name": "John Johnson",
    "bsb": "012345",
    "accountNumber": "12345678",
    "email": "john@johnson.com"
  },
  "externalReference": "Some reference"
}
```

```json
{
  "amount": 12345,
  "currency": "DKK",
  "paymentTitle": "Other currency test",
  "beneficiary": {
    "name": "John Johnson",
    "iban": "DE07500105176551562526",
    "swiftBic": "BIGBPLPW"
  },
  "externalReference": "Some reference"
}
```

--------------------------------

### Account Balance API Response Example

Source: https://docs.volt.io/implementation/volt-accounts/account-balance

This is an example of the JSON response when requesting an account balance via the API. Ensure you have obtained an access token through authentication.

```json
{
    "availableBalance": 998389,
    "currency": "GBP",
    "timestamp": "2024-05-29T09:57:41+00:00"
}
```

--------------------------------

### Example Signature Output

Source: https://docs.volt.io/implementation/accounts/outgoing-payments/signing-request

A sample signature string generated from the provided header and payload.

```text
oUjLLtQigBniTiYswfE0JAjMiYXtIlNtVi1Lr1jqBx103vXgVtEdWApUMpG3wze3qVXD_APA2Sk8oLV4DGeBb5pN7yRGeCdxoV3IsikCVs6rn2Q2Jat-bReQMX39F7-Rpn7RznjHUsyWWcNbDKy1wRFcEnDJBVdb_1lKdFBPWaKMkB1Yd8t8X2va6mq7pJXPAMS36Gwc37vULZvdw4D-49r8mcbEGnNXwkcuZ08hMk4UsmM0kxLeNcrVD3wZtuU0N43u1trlPnuX9RDOOh9Gz0fEH1fwxdveAZaMOOWr7IPHBeV8nZXHxt1lpwJ-dpAsSDMvCFhr-MHuOQDDdqsfhQ
```

--------------------------------

### Eligible Beneficiaries Response Example

Source: https://docs.volt.io/implementation/volt-accounts/payouts/payouts-api

Example JSON response body returned when querying eligible beneficiaries.

```json
[
  {
    "name": "John Johnson",
    "accountNumber": "12345678",
    "sortCode": "404452",
    "iban": null,
    "swiftBic": null
  }
]
```

--------------------------------

### Test notification example

Source: https://docs.volt.io/implementation/webhooks/signature-verification

A concrete example of a test notification payload.

```text
{}|12345678|2.0
```

--------------------------------

### Onboarding Status Examples

Source: https://docs.volt.io/implementation/webhooks/accounts/onboarding

JSON payloads representing various onboarding and account request states.

```json
{
  "id": "43ebfac8-a569-49b1-9bfc-775182b5f369",
  "status": "REJECTED",
  "statusReason": "Onboarding rejected for testing",
  "createdAt": "2026-01-27T15:17:09.138162+01:00",
  "updatedAt": "2026-01-27T15:17:11.150896+01:00",
  "completedAt": "2026-01-27T15:17:11.150896+01:00"
}
```

```json
{
  "id": "c651bd3e-5923-46d9-a6c5-c7c2a4dd0a79",
  "onboardingEntityId": "8687c787-8fb7-4f90-aaa1-b1cce88fe713",
  "accountId": "83cfd2e8-606d-4f3d-b3b2-cc1bd5e55acd",
  "status": "COMPLETED",
  "createdAt": "2026-01-28T18:07:00.825742Z",
  "completedAt": "2026-01-28T18:07:08.104358359Z"
}
```

```json
{
  "id": "f8f934fc-190d-4cb1-b626-6e0996547f65",
  "onboardingEntityId": "8687c787-8fb7-4f90-aaa1-b1cce88fe713",
  "accountId": "afd446d3-4a9e-4787-8a1d-e6d400c7c725",
  "status": "COMPLETED",
  "createdAt": "2026-01-28T18:01:40.621809Z",
  "completedAt": "2026-01-28T18:02:08.052089072Z"
}
```

```json
{
  "id": "096bd8d0-1b46-4e37-82cd-d0ce2a2b9b44",
  "onboardingEntityId": "8687c787-8fb7-4f90-aaa1-b1cce88fe713",
  "status": "FAILED",
  "statusReason": "Named account order failed due to sandbox scenario",
  "createdAt": "2026-01-28T18:03:06.242767Z",
  "completedAt": "2026-01-28T18:03:07.956976154Z"
}
```

```json
{
  "id": "60290bb9-71e6-400a-a4b3-2d9789e681fa",
  "status": "ADDITIONAL_INFO_REQUIRED",
  "statusReason": "Additional information required for testing",
  "createdAt": "2026-01-28T18:49:49.52091Z",
  "updatedAt": "2026-01-28T18:49:51.624262789Z"
}
```

--------------------------------

### Example notification body

Source: https://docs.volt.io/implementation/webhooks/signature-verification

This is an example of a notification body containing real data, which should be used as a single, unformatted string for signature verification.

```json
{"payment":"4a96elcb-8ae0-426c-a95e-d34f18fe32ad","reference":"EXAMPLE123","amount":8888,"status":"PENDING","detailedStatus":"BANK_REDIRECT"}
```

--------------------------------

### Report Status Response Example

Source: https://docs.volt.io/implementation/power-tools/reporter/fetch-download

This is an example of a successful response when checking a report's status. The `status` field indicates the current state of the report generation.

```json
{
  "id": "report-uuid-here",
  "type": "PAYMENTS",
  "status": "REPORT_AVAILABLE",
  "createdAt": "2024-01-15T10:30:00Z",
  "generatedAt": "2024-01-15T10:31:45Z"
}
```

--------------------------------

### Create a Payment Request

Source: https://docs.volt.io/implementation/essentials/authentication

Example of using the access token to perform a payment creation request.

```http
POST https://api.volt.io/payments \
Authorization: Bearer YOUR_ACCESS_TOKEN \
Content-Type: application/json \
{ ... }
```

--------------------------------

### GET /onboarding/individual/{onboardingEntityId}

Source: https://docs.volt.io/implementation/accounts/integration-guides/onboarding

Retrieves the full onboarding payload for a specific entity.

```APIDOC
## GET /onboarding/individual/{onboardingEntityId}

### Description
Retrieves the full onboarding payload for a specific entity.

### Method
GET

### Endpoint
onboarding/individual/{onboardingEntityId}

### Parameters
#### Path Parameters
- **onboardingEntityId** (string) - Required - The unique identifier for the onboarding entity.
```

--------------------------------

### Retrieve Rejected Payout Details

Source: https://docs.volt.io/implementation/volt-accounts/payouts/payouts-api

Response example for a payout created on Fuzebox that was rejected by a user.

```http
GET /payouts/94fcc71e-6244-4f77-a86b-99eb7601b843
```

```json
{
  "id": "efffed42-40f7-4bd2-840d-908aae9a33ad",
  "status": "PAYOUT_REJECTED_BY_USER",
  "createdAt": "2019-08-24T14:15:22Z",
  "amount": 500,
  "currency": "EUR",
  "paymentTitle": "Payout123456",
  "beneficiary": {
    "name": "John Johnson",
    "accountNumber": "12345678",
    "sortCode": "404452",
    "iban": "DK8389009999910135",
    "swiftBic": "SXPYDKKKXXX"
  },
  "sender": {
    "sortCode": "404777",
    "accountNumber": "87654321",
    "iban": "DK8389009999910135",
    "swiftBic": "SXPYDKKKXXX"
  },
  "approvals": [
    {
      "user": {
        "name": "Robert Robertson"
      },
      "type": "REJECTION",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "externalReference": "Some reference"
}
```

--------------------------------

### POST /gateway/account-access

Source: https://docs.volt.io/implementation/power-tools/verify/integration-guide

Initiate an account access request to start the bank verification flow.

```APIDOC
## POST /gateway/account-access

### Description
Initiate an account access request to start the verification flow.

### Method
POST

### Endpoint
https://api.volt.io/gateway/account-access

### Parameters
#### Request Body
- **informationSystem** (string) - Required - The system used (e.g., OPEN_BANKING)
- **internalReference** (string) - Required - Your internal reference ID
- **subject** (object) - Required - Subject details including reference and email
- **scopes** (array) - Required - List of requested scopes (e.g., ACCOUNTS, BALANCES)
- **device** (object) - Required - Device information including IP and userAgent
- **communication** (object) - Required - Webhook and redirect URL configurations
- **termsAndConditionsAccepted** (boolean) - Required - Confirmation of T&C acceptance

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the access request
- **accountAccessFlow** (object) - Contains redirect details for the user
```

--------------------------------

### Create Payouts Report Request

Source: https://docs.volt.io/api-reference/reporter/post-reports-payouts

Example request for generating a payouts report using cURL.

```bash
curl -X POST "https://gateway.sandbox.volt.io/reports/payouts" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2019-08-24T14:15:22+00:00",
    "endDate": "2019-08-24T14:15:22+00:00",
    "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    "accountId": "12d8e330-2878-4742-a86f-dbbb3bf52234"
  }'
```

--------------------------------

### Get payments received on or since a specific date (Production)

Source: https://docs.volt.io/implementation/volt-accounts/reporting/introduction

This example shows how to retrieve all payments with a 'RECEIVED' status that were updated on or after January 31, 2021, using the Volt API production environment.

```http
GET https://api.volt.io/payments?status=RECEIVED&statusUpdate[newStatus]=RECEIVED&statusUpdate[createdAt][gte]=20210131000000
```

--------------------------------

### POST /onboarding/individual

Source: https://docs.volt.io/implementation/accounts/integration-guides/onboarding

Initiates the individual onboarding process.

```APIDOC
## POST /onboarding/individual

### Description
Initiates the individual onboarding process.

### Method
POST

### Endpoint
onboarding/individual
```

--------------------------------

### Get payments received on or since a specific date (Sandbox)

Source: https://docs.volt.io/implementation/volt-accounts/reporting/introduction

This example shows how to retrieve all payments with a 'RECEIVED' status that were updated on or after January 31, 2021, using the Volt API sandbox environment.

```http
GET https://api.sandbox.volt.io/payments?status=RECEIVED&statusUpdate[newStatus]=RECEIVED&statusUpdate[createdAt][gte]=20210131000000
```

--------------------------------

### Present SwiftUI View in UIKit ViewController

Source: https://docs.volt.io/implementation/mobile-sdk

Use UIHostingController to embed SwiftUI views within an existing UIKit-based project. This example shows how to present the Volt welcome view.

```swift
import SwiftUI
import VoltSDK

private var voltSdk = VoltSDK.shared

// Presenting the SwiftUI view in a UIKit ViewController
let swiftUIView = voltSdk.startWelcomeView {
  print("Welcome view ended")
}

let hostingController = UIHostingController(rootView: swiftUIView)
present(hostingController, animated: true, completion: nil)
```

--------------------------------

### Get payments received between two dates (Production)

Source: https://docs.volt.io/implementation/volt-accounts/reporting/introduction

This example demonstrates how to retrieve payments with a 'RECEIVED' status that were updated between January 25, 2021, and January 31, 2021, using the Volt API production environment.

```http
GET https://api.volt.io/payments?status=RECEIVED&statusUpdate[newStatus]=RECEIVED&statusUpdate[createdAt][lte]=20210131000000&statusUpdate[createdAt][gte]=20210125235959
```

--------------------------------

### Get payments received between two dates (Sandbox)

Source: https://docs.volt.io/implementation/volt-accounts/reporting/introduction

This example demonstrates how to retrieve payments with a 'RECEIVED' status that were updated between January 25, 2021, and January 31, 2021, using the Volt API sandbox environment.

```http
GET https://api.sandbox.volt.io/payments?status=RECEIVED&statusUpdate[newStatus]=RECEIVED&statusUpdate[createdAt][lte]=20210131000000&statusUpdate[createdAt][gte]=20210125235959
```

--------------------------------

### Setting the Environment (Mobile SDK)

Source: https://docs.volt.io/implementation/mobile-sdk/implementation

Guides on how to set the Volt Mobile SDK environment to Sandbox or Production for Android and iOS.

```APIDOC
## Setting the environment

In the `Application` class (Android) or within the app's main entry point (iOS), you should set the environment you're running the app in – this will either be `Sandbox` for testing or `Production` to enable real bank payments to be made.

### Android Example (Sandbox)
```kotlin
import io.volt.sdk.Volt

class App : Application() {

  override fun onCreate() {
    super.onCreate()

    Volt.init(
      environment = VoltEnvironment.Sandbox,
    )
  }
}
```

### iOS Example (Sandbox)
```swift
import SwiftUI
import VoltSDK

@main
struct VoltApp: App {
  var body: some Scene {
    WindowGroup {
      ExampleApp()
        .onAppear {
          VoltSDK.shared.setEnvironment(environment: .sandbox)
        }
    }
  }
}
```

**Notes:**
- Use `VoltSDK.shared.setEnvironment(environment: .sandbox)` or `.production` to set the environment.
- `.sandbox` mode does not involve real money exchange and is safe for testing.
- You can switch environments at runtime, but payments are not shared between modes.
- Check the current environment using `VoltSDK.shared.getEnvironment().isSandbox`.
- Obtain the API host using `VoltSDK.shared.getEnvironment().host` for other Volt API requests.
```

--------------------------------

### POST /onboarding/{onboardingEntityId}/submit

Source: https://docs.volt.io/implementation/accounts/integration-guides/onboarding

Submits the onboarding process for review. Supports various testing scenarios via headers.

```APIDOC
## POST /onboarding/{onboardingEntityId}/submit

### Description
Submits the onboarding process for review. Supports various testing scenarios via headers.

### Method
POST

### Endpoint
onboarding/{onboardingEntityId}/submit

### Parameters
#### Path Parameters
- **onboardingEntityId** (string) - Required - The unique identifier for the onboarding entity.

#### Request Headers
- **X-Volt-Testing-Scenario** (string) - Optional - Used to trigger specific testing outcomes (e.g., ONBOARDING_ADDITIONAL_INFO_REQUIRED, ONBOARDING_REJECTED, ONBOARDING_EXPIRED).
```

--------------------------------

### Initiate a Payment

Source: https://docs.volt.io/api-reference/payments/payments/post-payments

Use this cURL command to initiate a new payment request to the Volt.io gateway.

```bash
curl -X POST "https://gateway.sandbox.volt.io/payments" \
  -H "Idempotency-Key: 85136c79cbf9fe36bb9d05d0639c70c265c18d37" \
  -H "X-Volt-Api-Version: 1" \
  -H "X-Volt-Initiation-Channel: api" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 10000,
    "internalReference": "H35X48Y4FWOD6G3S",
    "paymentReference": "T1Qwerty",
    "payer": {
      "reference": "JDOE-101",
      "firstName": "John",
      "lastName": "Doe",
      "organisationName": "JD Holdings",
      "email": "johndoe@example.com"
    },
    "device": {
      "ip": "192.168.0.1",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
      "fingerprint": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
    },
    "paymentSystem": "OPEN_BANKING_EU",
    "openBankingEU": {
      "type": "SERVICES",
      "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49",
      "statementDescriptor": "Black coffee - big",
      "validityPeriod": 1440,
      "accountIdentifiers": {
        "iban": "DE75512108001245126199"
      }
    },
    "beneficiary": {
      "name": "Jane Doe",
      "accountIdentifiers": {
        "iban": "PL10105000997603123456789123"
      }
    },
    "communication": {
      "notifications": {
        "url": "https://mywebsite.com/webhooks"
      },
      "return": {
        "urls": {
          "unified": {
            "url": "https://mywebsite.com/payment"
          },
          "success": {
            "url": "https://mywebsite.com/payment/success"
          },
          "failure": {
            "url": "https://mywebsite.com/payment/failed"
          },
          "pending": {
            "url": "https://mywebsite.com/payment/pending"
          },
          "cancel": {
            "url": "https://mywebsite.com/payment/cancelled"
          }
        },
        "queryString": "id=xyz"
      }
    },
    "displayInfo": [
      {
        "key": "Product SKU",
        "value": "87ec73a0"
      }
    ],
    "termsAndConditionsAccepted": true
  }'
```

--------------------------------

### Initialize Volt SDK in Android

Source: https://docs.volt.io/implementation/mobile-sdk/implementation

Initialize the Volt SDK with the appropriate environment (Sandbox or Production) in your Application class. Use VoltEnvironment.Sandbox for testing.

```kotlin
import io.volt.sdk.Volt

class App : Application() {

  override fun onCreate() {
    super.onCreate()

    Volt.init(
      environment = VoltEnvironment.Sandbox,
    )
  }
}
```

--------------------------------

### Configure Gradle Maven Repository

Source: https://docs.volt.io/implementation/mobile-sdk/installation

Add this Maven configuration to your settings.gradle.kts file. A private token from Volt is required for authentication.

```kotlin
maven {
  url = uri("https://gitlab.com/api/v4/projects/49120335/packages/maven")
  credentials(HttpHeaderCredentials::class) {
    name = "Private-Token"
    value = "<private-token>"
  }

  authentication {
    create("header", HttpHeaderAuthentication::class)
  }
}
```

--------------------------------

### POST /payments Response Structure

Source: https://docs.volt.io/implementation/payments/integration-guides/api-only-guide

Example response indicating that the payment initiation flow is waiting for user input such as username and password.

```json
{
    // ...
    "paymentInitiationFlow": {
        "status": "WAITING_FOR_INPUT",
        "requiredInput": [
            {
                "name": "SCA_USERNAME",
                "propertyPath": "sca.username"
            },
            {
                "name": "SCA_PASSWORD",
                "propertyPath": "sca.password"
            }
        ]
    }
}
```

--------------------------------

### Example Connect Report Data (CSV)

Source: https://docs.volt.io/implementation/power-tools/reporter/connect-report

This is an example of the data structure you can expect in a Connect report when exported to CSV format. It includes various transaction types and their associated details.

```csv
transactionType,paymentId,refundId,payoutId,batchId,amount,currency,transactionStatus,balanceBefore,balanceAfter,valueDate,createdAt,beneficiaryName,beneficiaryIban,merchantReference
PAYMENT,pay-001,,,,10000,EUR,RECEIVED,50000,60000,2024-01-15,2024-01-15T10:30:00Z,,,ORDER-001
PAYMENT,pay-002,,,,25000,EUR,SETTLED,60000,85000,2024-01-15,2024-01-15T11:00:00Z,,,ORDER-002
REFUND,pay-001,ref-001,,,10000,EUR,CONFIRMED,85000,75000,2024-01-16,2024-01-16T09:00:00Z,John Doe,DE89370400440532013000,REFUND-001
PAYOUT,,,payout-001,,50000,EUR,COMPLETED,75000,25000,2024-01-17,2024-01-17T14:00:00Z,Supplier Ltd,DE89370400440532013001,PAYOUT-001
SETTLEMENT,,,,batch-001,25000,EUR,COMPLETED,25000,0,2024-01-18,2024-01-18T00:00:00Z,,,
CREDIT,,,,,5000,EUR,RECEIVED,0,5000,2024-01-19,2024-01-19T10:00:00Z,,,CREDIT-001
```

--------------------------------

### POST /notifications/mocker

Source: https://docs.volt.io/implementation/volt-accounts/collections/testing-credits

Simulates incoming EUR and GBP credits in the Sandbox environment.

```APIDOC
## POST https://api.sandbox.volt.io/notifications/mocker

### Description
Simulates incoming EUR and GBP credits for testing purposes in the Sandbox environment.

### Method
POST

### Endpoint
https://api.sandbox.volt.io/notifications/mocker

### Request Body
- **voltPaymentId** (string) - Required
- **accountName** (string) - Required
- **currency** (string) - Required
- **type** (string) - Required
- **status** (string) - Required
- **receivedAt** (string) - Required
- **amount** (number) - Required
- **reference** (string) - Required
- **iban** (string|null) - Optional
- **swiftBic** (string|null) - Optional
- **accountNumber** (string) - Required
- **sortCode** (string) - Required
- **payer** (object) - Required
- **customerId** (string) - Required
- **virtualAccountId** (string) - Required
- **virtualAccountIdentifiers** (object) - Required

### Request Example
{
  "voltPaymentId": "1ec66986-9174-420d-b72f-9367e6c1279e",
  "accountName": "Test Account",
  "currency": "EUR",
  "type": "payin",
  "status": "CONFIRMED",
  "receivedAt": "2024-11-03T02:30:00+01:00",
  "amount": 321,
  "reference": "test reference",
  "iban": null,
  "swiftBic": null,
  "accountNumber": "12345678",
  "sortCode": "123456",
  "payer": {
    "name": "John Doe",
    "iban": "PL17109024026987316159914944",
    "swiftBic": "BUKBGB22",
    "accountNumber": null,
    "sortCode": null
  },
  "customerId": "eeeeeeee-0001-eeee-eeee-eeeeeeeeeeee",
  "virtualAccountId": "65a4c575-df83-41f6-8333-21068b2a6864",
  "virtualAccountIdentifiers": {
    "iban": "DK2450517187342686",
    "swiftBic": "DKNBDKKKXXX"
  }
}
```

--------------------------------

### Example Volt Redirect Payloads

Source: https://docs.volt.io/implementation/payments/integration-details/mobile-redirects-app-to-app

These are example JSON payloads that Volt checkout will send to your `window.voltRedirectCallback` function when a redirect occurs. They indicate whether the redirect is to a bank app or back to the merchant, and include a URL and optional result status.

```json
{ "type": "bank_redirect", "url": "https://bank-app.example.com/authorize?token=abc" }
```

```json
{ "type": "merchant_redirect", "url": "your-app://checkout/cancel", "result": "cancel" }
```

```json
{ "type": "merchant_redirect", "url": "your-app://checkout/success", "result": "success" }
```

```json
{ "type": "merchant_redirect", "url": "your-app://checkout/error", "result": "exception" }
```

--------------------------------

### Selecting a Bank (Mobile SDK)

Source: https://docs.volt.io/implementation/mobile-sdk/implementation

Guides on how to initiate and handle bank selection using the Volt Mobile SDK for Android and iOS.

```APIDOC
## Selecting a bank

If there is a bank returned from the `/linked-accounts` endpoint, bank selection can be skipped. If there is no bank returned or the shopper doesn't want to use the previously-used bank, then a new bank selection will be required. Request bank selection through the SDK, and wait for the selected bank.

### Android
```kotlin
import io.volt.sdk.Volt

val launcher = registerForActivityResult(
  StartActivityForResult(),
  ::onBankSelected,
)

Volt.selectBank(
  context: Context,
  launcher: ActivityResultLauncher<Intent>,
  customerId: String,
)

fun onBankSelected(activityResult: ActivityResult?) {
  val bankData = Volt.getBankData(activityResult)
}
```

### iOS
```swift
import VoltSDK

private var voltSdk = VoltSDK.shared
voltSdk.selectBank(customerId: String) { bankModel in
  print("Bank selection view ended")
  print(bankModel)
}
```
```

--------------------------------

### GET /institutions

Source: https://docs.volt.io/api-reference/payments

Retrieve a list of all available institutions.

```APIDOC
## GET /institutions

### Description
Get list of institutions. All the details can be used for creating a institution selection UI, along with required account identifiers inputs.

### Method
GET

### Endpoint
/institutions
```

--------------------------------

### GET /reports - Get Available Reports

Source: https://docs.volt.io/api-reference/reporter/post-reports-audit-log

Fetches a list of all generated reports. Reports can be downloaded using their ID via the `/reports/{id}/download` endpoint. By default, it returns reports for the entire customer hierarchy; a `customerId` query parameter can limit the results.

```APIDOC
## GET /reports

### Description
This endpoint will allow you to fetch a list containing all the reports you've generated. Use the ```id``` of the report to download it using the ```/reports/{id}/download``` endpoint. By default, it will return a complete list of reports for your entire customer hierarchy. Providing a ```customerId``` in the query will allow you to limit the list to reports available for one particular merchant.

### Method
GET

### Endpoint
`/reports`

### Parameters
#### Query Parameters
- **customerId** (string) - Optional - Filters the list to reports available for a particular merchant. Format: `uuid`.
```

--------------------------------

### POST /onboarding/{onboardingEntityId}/documents

Source: https://docs.volt.io/implementation/accounts/integration-guides/onboarding

Uploads documents for an onboarding entity.

```APIDOC
## POST /onboarding/{onboardingEntityId}/documents

### Description
Uploads documents for an onboarding entity.

### Method
POST

### Endpoint
onboarding/{onboardingEntityId}/documents

### Parameters
#### Path Parameters
- **onboardingEntityId** (string) - Required - The unique identifier for the onboarding entity.
```

--------------------------------

### Retrieve Transactions via cURL

Source: https://docs.volt.io/api-reference/accounts/transactions/get-transactions

Example request to fetch transactions using the cURL command-line tool.

```bash
curl -X GET "https://accounts.sandbox.volt.io/transactions" \
  -H "X-Volt-Api-Version: 1" \
  -H "Authorization: Bearer "
```

--------------------------------

### GET /institutions/{id}

Source: https://docs.volt.io/api-reference/payments

Fetch details for a specific institution.

```APIDOC
## GET /institutions/{id}

### Description
Fetch particular institution details.

### Method
GET

### Endpoint
/institutions/{id}
```

--------------------------------

### Get institution details

Source: https://docs.volt.io/api-reference/payments/payments/patch-payment

Fetches details for a specific financial institution.

```APIDOC
## GET /institutions/{id}

### Description
Fetches details for a specific financial institution.

### Method
GET

### Endpoint
`https://gateway.sandbox.volt.io/institutions/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - Identifier of the institution.

#### Header Parameters
- **X-Volt-Api-Version** (integer) - Required - Version of the API used. Currently, version `1` is the only version.
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (string) - Description
- **name** (string) - Description
- **countryCode** (string) - Description
- **bic** (string) - Description

#### Response Example
```json
{
  "id": "cdae5c01-a629-4362-be56-52101ec22a49",
  "name": "Example Bank",
  "countryCode": "DE",
  "bic": "DEUTDEFF500"
}
```

#### Error Responses
- **401** (UNAUTHORISED): Unauthorised.
- **404** (RESOURCE_NOT_FOUND): Not found.
```

--------------------------------

### GET /reports/{id}

Source: https://docs.volt.io/api-reference/reporter/get-reports-id-download

Fetches the details of a specific report by its ID.

```APIDOC
## GET /reports/{id}

### Description
This endpoint allows fetching the details of a specific report. Note that this will return the details of the report only. To download the report as a CSV file, use the /reports/{id}/download endpoint.

### Method
GET

### Endpoint
https://gateway.sandbox.volt.io/reports/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - ID of report
```

--------------------------------

### POST /payments response structure

Source: https://docs.volt.io/implementation/payments/integration-guides/api-only-guide

Example response from the payment initiation endpoint showing the redirect URLs.

```json
{
    //...
    "paymentInitiationFlow": {
        "status": "PROCESSING",
        "details": {
          "reason": "AWAITING_USER_REDIRECT",
            "redirect": {
                "url": "https://vo.lt/short",
                "directUrl": "https://myBank.com/authorisation?code=xyz"
            }
        }
    }
    //...
}
```

--------------------------------

### Example Encoded Header

Source: https://docs.volt.io/implementation/accounts/outgoing-payments/signing-request

The resulting base64Url encoded string of the JWT header.

```text
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNlMTYxYzQ5LTQzNzMtNGIwNy04MmZhLTIxNzk5OGY2YjNlOCJ9
```

--------------------------------

### Create Named Account Order Request

Source: https://docs.volt.io/api-reference/accounts/named-accounts/create-named-account-order

Example cURL request to create a named account order.

```bash
curl -X POST "https://accounts.sandbox.volt.io/orders/named-accounts" \
  -H "Idempotency-Key: 85136c79cbf9fe36bb9d05d0639c70c265c18d37" \
  -H "X-Volt-Api-Version: 1" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "onboardingEntityId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "currency": "EUR",
    "communication": {
      "notifications": {
        "url": "https://mywebsite.com/webhooks"
      }
    }
  }'
```

--------------------------------

### GET /transactions/{transactionId}

Source: https://docs.volt.io/implementation/webhooks/accounts/payments

Retrieves the details of a specific transaction by its unique identifier.

```APIDOC
## GET /transactions/{transactionId}

### Description
Retrieves the full details of a transaction, including status, amount, currency, and beneficiary/sender information.

### Method
GET

### Endpoint
/transactions/{transactionId}

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - The unique identifier of the transaction.

### Response
#### Success Response (200)
- **id** (string) - Transaction ID
- **status** (string) - Current status of the transaction
- **operation** (string) - Operation type (e.g., INCOMING)
- **type** (string) - Transaction type
- **createdAt** (string) - Timestamp of creation
- **updatedAt** (string) - Timestamp of last update
- **amount** (number) - Transaction amount
- **currency** (string) - Currency code
- **beneficiary** (object) - Beneficiary details
- **sender** (object) - Sender details

#### Response Example
{
  "id": "f291b32a-1252-494f-ae5b-f487983d9f22",
  "status": "COMPLETED",
  "operation": "INCOMING",
  "type": "MANUAL_CREDIT",
  "createdAt": "2026-01-27T21:21:14.147327Z",
  "updatedAt": "2026-01-27T21:21:15.41338Z",
  "amount": 100,
  "currency": "EUR",
  "beneficiary": {
    "customerId": "3ddba750-89e7-45a2-bdc9-99d12018aa34",
    "accountId": "5399e2e9-2693-48a6-bc35-fe4a827d936c",
    "name": "Your account name",
    "accountIdentifiers": {
      "iban": "DE23874043682755038080"
    }
  }
}
```

--------------------------------

### Initiate payment via SDK

Source: https://docs.volt.io/implementation/mobile-sdk/implementation

Trigger the payment flow using the native SDK methods for Android and iOS.

```kotlin
Volt.payWithSelectedBank(
 fragmentManager: FragmentManager,
 token: String,
)
```

```swift
VStack(spacing: 44) {
  //View content
}
.voltPaymentSheet(token: $viewModel.token)
```

--------------------------------

### GET /payments

Source: https://docs.volt.io/implementation/volt-accounts/reporting/introduction

Retrieve a list of payments filtered by status and creation date.

```APIDOC
## GET /payments

### Description
Retrieve a summary of payments received for reconciliation purposes. Use filters to narrow down results by status and date ranges.

### Method
GET

### Endpoint
https://api.volt.io/payments (or https://api.sandbox.volt.io/payments for sandbox)

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by payment status (e.g., RECEIVED).
- **statusUpdate[newStatus]** (string) - Optional - Filter by the new status (e.g., RECEIVED).
- **statusUpdate[createdAt][gte]** (string) - Optional - Filter for timestamps on or later than a specific date/time (format: yyyymmddhhmmss).
- **statusUpdate[createdAt][lte]** (string) - Optional - Filter for timestamps on or before a specific date/time (format: yyyymmddhhmmss).

### Request Example
GET https://api.volt.io/payments?status=RECEIVED&statusUpdate[newStatus]=RECEIVED&statusUpdate[createdAt][gte]=20210131000000

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the payment.
- **currency** (object) - Currency details.
- **bank** (object) - Bank details.
- **amount** (integer) - Payment amount.
- **type** (string) - Payment type.
- **uniqueReference** (string) - Unique reference for the payment.
- **merchantInternalReference** (string) - Merchant internal reference.
- **status** (string) - Current status of the payment.
- **createdAt** (string) - Timestamp of creation.

#### Response Example
[
  {
    "id": "662384a0-9734-4556-a8bd-3f1e774e2a3c",
    "currency": {
      "id": "GBP",
      "name": "Pound Sterling",
      "decimal": 2,
      "active": true
    },
    "bank": {
      "id": "662384a0-9734-4556-a8bd-3f1e774e2a3c",
      "name": "Barclays Bank",
      "country": {
        "id": "GB",
        "name": "United Kingdom"
      },
      "officialName": "Barclays Bank Plc",
      "branchName": "Barclays Bank Branch Plc",
      "shortBranchName": "Barclays Bank Branch",
      "active": true,
      "logo": "https://cdn.volt.io/banks/logos/xx_barclays_bank.png",
      "icon": "https://cdn.volt.io/banks/icons/xx_barclays_bank.png"
    },
    "amount": 12345,
    "type": "OTHER",
    "uniqueReference": "sale123456",
    "merchantInternalReference": "MV91bmlxdWVfcmREVO12MV91bmlxdWVfcmREVO12MV91bmlxdWVfcmREVO12MV91bmlxdWVfcmREVO12MV91bmlxdWVfcmREVO12",
    "status": "RECEIVED",
    "createdAt": "2020-06-02T05:48:53.000Z"
  }
]
```

--------------------------------

### Initialize Volt SDK in Android

Source: https://docs.volt.io/implementation/mobile-sdk

Initialize the Volt SDK in your Android application's onCreate method. Ensure the environment is set correctly.

```kotlin
import io.volt.sdk.Volt

class App : Application() {
  override fun onCreate() {
    super.onCreate() 
    Volt.init(
      environment = VoltEnvironment.Sandbox,
    )
  }
}
```

--------------------------------

### Fetch raw banks list

Source: https://docs.volt.io/implementation/mobile-sdk/implementation

Retrieve a list of available banks for custom UI implementations.

```bash
curl --request GET \
  --url http://api.localhost/checkout/banks/{customerId}/{countryCode}/{currencyCode} \
  --header 'Accept: application/json'
```