# Payments

## List payment statuses for an account

 - [GET /v1/accounts/{accountNumber}/payments](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/accounts/transactionstatus_getaccounttransactionstatuses.md): Retrieves status information for all payments associated with a specific account. This endpoint:
            
- Provides comprehensive payment status details including type, status, transaction ID, external reference, remittance information, amounts, value date, and exchange rate.
- Supports both JSON and CSV response formats based on the Accept header.
- Supports cursor-based pagination for efficient handling of large payment status datasets.

### Pagination
This endpoint uses cursor-based pagination with server-side result-set management:
- First Request: Optionally specify pageSize (default: 100, max: 1000). The server creates a cursor and returns a pageToken.
- Subsequent Requests: Use the pageToken from previous responses with pageStart to navigate pages.
- Page Token: Contains encoded pagination context including pageSize, so don't specify pageSize in subsequent requests.
- Total Pages: Calculate using Math.ceil(total_size / page_size) from the response metadata.

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/accounts/{accountNumber}/payments

### Sample Request in JavaScript

javascript
async function getAllPaymentStatusesPaginated(accountNumber) {
  try {
    let allPaymentStatuses = [];
    let pageStart = 1;
    let pageToken = null;
    let totalPages = 0;

    do {
      // Build URL with pagination parameters
      let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
      const params = new URLSearchParams();
      
      if (pageStart === 1) {
        // First request: specify pageSize
        params.append('pageSize', '100');
      } else {
        // Subsequent requests: use pageToken and pageStart
        params.append('pageToken', pageToken);
        params.append('pageStart', pageStart.toString());
      }
      
      if (params.toString()) {
        url += '?' + params.toString();
      }

      const response = await fetch(url, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(Error: ${errorData.message || 'Unknown error'});
      }

      const data = await response.json();
      console.log(Page ${pageStart} data:, data);

      // Store pagination info from first request
      if (pageStart === 1 && data.meta && data.meta.pagination) {
        pageToken = data.meta.pagination.page_token;
        totalPages = Math.ceil(data.meta.pagination.total_size / data.meta.pagination.page_size);
        console.log(Total pages: ${totalPages}, Page token: ${pageToken});
      }

      // Collect payment statuses from this page
      if (data.data && data.data.length > 0) {
        allPaymentStatuses.push(...data.data);
        console.log(Collected ${data.data.length} payment statuses from page ${pageStart});
      }

      pageStart++;
    } while (pageStart  {
      console.log(Payment ${index + 1}:, payment.transactionId);
      console.log('Type:', payment.type);
      console.log('Status:', payment.status);
      console.log('External Reference:', payment.externalReference);
      console.log('Remittance Information:', payment.remittanceInformation);
      console.log('Value Date:', payment.valueDate);
      console.log('Debit Amount:', ${payment.debitAmount.amount} ${payment.debitAmount.currency});
      if (payment.creditAmount && payment.creditAmount.amount) {
        console.log('Credit Amount:', ${payment.creditAmount.amount} ${payment.creditAmount.currency});
      }
      console.log('-------------------');
    });

    return allPaymentStatuses;
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
    throw error;
  }
}

// Alternative: Get single page of payment statuses
async function getPaymentStatusesPage(accountNumber, pageStart = 1, pageToken = null) {
  try {
    let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
    const params = new URLSearchParams();
    
    if (pageStart === 1 && !pageToken) {
      params.append('pageSize', '50'); // Custom page size
    } else {
      params.append('pageToken', pageToken);
      params.append('pageStart', pageStart.toString());
    }
    
    if (params.toString()) {
      url += '?' + params.toString();
    }

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Error: ${errorData.message || 'Unknown error'});
    }

    const data = await response.json();
    console.log('Payment statuses page:', data);
    return data;
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
    throw error;
  }
}

// Example usage:
getAllPaymentStatusesPaginated('123456789'); // Retrieves all payment statuses across multiple pages
// OR
getPaymentStatusesPage('123456789', 1).then(firstPage => {
  console.log('First page:', firstPage);
  // Use firstPage.meta.pagination.page_token for subsequent requests
});


Required Permission: get-payment-status

This endpoint requires the permission claim get-payment-status to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

## ACH Local Payment

 - [POST /v1/payments/ach-local](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/payments/achlocalpayments_post.md): Initiates a domestic same-currency bank transfer over the ACH clearing network. The request carries debtor account, instructed amount, debit currency, creditor account + bank reference, and 1–2 lines of remittance information. JSON and CSV response formats are supported via the Accept header.
            
### Supported Currencies
Only USD and BMD are accepted. debitCurrency and instructedAmount.currency must be identical - cross-currency is not supported on this endpoint.
            
### Settlement and Cut-Off
Transfers settle same-day when submitted before 3:15 PM local AST; later submissions are queued for the next business day. The value/effective date in the response reflects the settlement date.
            
### Creditor Bank Reference
Provide creditorBank with the destination bank bankCode and currency.
The API validates this combination against the configured bank reference lookup.
If the bankCode and currency combination is not found, the API returns 400 Bad Request
with error code BANK_REFERENCE_NOT_FOUND.
            
The ACH local bank reference lookup contains the following values:
            
| Bank Code | Currency | Bank Name |
|-----------|----------|-----------|
| BUTTERFIELD | BMD | Bank of N.T. Butterfield & Sons |
| HSBC | BMD | HSBC Bermuda |
| CLARIEN | BMD | Clarien Bank Bermuda |
| BUTTERFIELD | USD | Bank of N.T. Butterfield & Sons |
| HSBC | USD | HSBC Bermuda |
| CLARIEN | USD | Clarien Bank Bermuda |
            
### Request basics
- Endpoint: POST https://api.bcb.bm/v1/payments/ach-local
- Authorization: Bearer {token} (required).
- Accept: application/json (default) or text/csv.
- Idempotency-Key: optional UUID v4 header (≤ 255 chars). See below.
            
### Idempotency
The API supports idempotency through the optional Idempotency-Key header. When supplied, the server caches the successful response and replays it on repeat calls.
- If no idempotency key is provided, the request is processed normally (duplicates are possible).
- If a valid UUID key is supplied, the system stores the response of the first 2xx outcome and replays it on subsequent calls with the same key.
- TTL (cache lifetime): the stored response is retained for a limited window (currently on the order of one hour). After expiry the same key is treated as a new request - but instructionIdentification deduplication still applies for 24 hours. Plan client-side retries to land inside the cache window.
- Scope: keys are partitioned by client/user, HTTP method, and request path. The same key on /payments/ach-local and /payments/swift is not shared - each endpoint has its own cache slot.
- Concurrency: if a second request with the same key arrives while the first is still in flight, the second is rejected with 409 Conflict and message "Request is already being processed." Wait and retry.
- Body mismatch: request bodies are not compared on replay. If you reuse a key with a different body, the original cached response is returned - the new body is ignored. Mint a fresh key for any logically different request.
- Non-2xx responses are not cached. A 4xx validation failure or 5xx server error can be retried with the same key and will execute again.
            
### Deduplication
A separate, business-level guard on the instructionIdentification field, applied independently of the Idempotency-Key header:
- Reusing an instructionIdentification for an active ACH local payment is rejected with 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID.
- Use a fresh instructionIdentification for each new payment intent. Reuse it (with the same Idempotency-Key) only when retrying the exact same payment.
- The deduplication window is currently configured as 24 hours from the first accepted request.
            
### How Idempotency-Key and instructionIdentification combine
They are independent mechanisms with different purposes.
- Idempotency-Key (header) is a transport-level retry token. It lets you safely retry the same HTTP call and get the original response replayed.
- instructionIdentification (body) is the business identifier of the payment. It is persisted on the payment record and forwarded downstream. To prevent the same payment intent from being submitted twice, a value that is already in flight or recently accepted is rejected with 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID (window: 24 hours).
            
| Idempotency-Key | instructionIdentification | Behaviour |
|---|---|---|
| no | no | No protection. Each call creates a new payment. |
| yes | no | HTTP retries of the same call replay the original response. A new Idempotency-Key creates a new payment. |
| no | yes | First call is processed normally. Reusing the same business identifier within 24 hours is rejected with 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID. The original success response is not replayed - record it client-side. |
| yes | yes | Recommended. HTTP retries of the same call replay the original response. A new Idempotency-Key reusing an in-flight instructionIdentification is rejected with 409. |
            
### Resilience: classifying responses
The dedupe and idempotency layers together cover three distinct failure modes. The status code tells you what to do next:
            
- 503 DEDUPE_LOCK_UNAVAILABLE - the duplicate-check store could not acquire its lock for instructionIdentification. The payment was not submitted to core banking. Safe to retry after a short backoff with the same instructionIdentification (and the same Idempotency-Key, if you used one). This is not "a duplicate was detected" - it is "we could not verify uniqueness right now."
- 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID - this instructionIdentification was already accepted within the 24-hour window. Do not retry the POST; query payment status to reconcile.
- 5xx, connection timeout, or no response - outcome unknown. Retry with the same Idempotency-Key and same instructionIdentification. The server will either replay the original 201 (if the first attempt landed) or return 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID (also indicating the first attempt landed).
            
Decision tree in pseudocode:
            
javascript
async function submitAchLocalPayment(paymentRequest, idempotencyKey) {
  for (let attempt = 1; attempt  keep BOTH values stable; the server will replay or short-circuit safely
retry(intent);
            
// After 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID
//   -> do NOT POST again; query status to reconcile
await getPaymentStatus(intent.instructionIdentification);

            
### Idempotency-Key lifecycle (client-side checklist)
- Mint the key before the HTTP call and persist it alongside the payment intent so a process restart or retry can still find it.
- Reuse it for every retry of the same intent; treat it as "spent" only after a terminal (2xx or non-retryable 4xx) response.
- Plan retries to land inside the cache window (~1 hour). Beyond that, instructionIdentification (24 h) is your remaining guard.
            
### Validation Rules
| Field | Constraint |
|-------|-----------|
| instructionIdentification | Optional, max 16 characters |
| debtorAccount.identification | Required, max 36 characters |
| debitCurrency | Required, exactly 3 characters, USD or BMD only |
| instructedAmount.amount | Required, max 18 characters, valid decimal (up to 2 decimal places) |
| instructedAmount.currency | Required, exactly 3 characters, USD or BMD only, must equal debitCurrency |
| creditorAccount.identification | Required, max 17 characters |
| creditorAccount.name | Required, max 22 characters |
| creditorBank.bankCode | Required, 1-100 characters (see Creditor Bank Reference below) |
| creditorBank.currency | Required, exactly 3 characters, must match debitCurrency |
| remittanceInformation | Required, 1–2 non-empty lines, each max 35 characters |
            
### Minimal Request Example
            
javascript
const res = await fetch('https://api.bcb.bm/v1/payments/ach-local', {
  method: 'POST',
  headers: {
    'Authorization':   Bearer ${token},
    'Content-Type':    'application/json',
    'Accept':          'application/json',
    'Idempotency-Key': idempotencyKey, // UUID v4, per payment intent
  },
  body: JSON.stringify(paymentRequest), // shape: see request schema below
});

            
The full request and response schemas, including field types and a worked example, are rendered below from the API contract.

Required Permission: payment-ach

This endpoint requires the permission claim payment-ach to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

## SWIFT Payment

 - [POST /v1/payments/swift](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/payments/payments_post.md): Initiates an international wire transfer over the SWIFT network. The request carries source and destination account information, payment amount and currency, beneficiary details, and remittance/reference information. Both JSON and CSV response formats are supported via the Accept header.
            
### Cross-Currency FX
For cross-currency payments you may supply the debit amount instead of the instructed amount (additive format):
- Send debitAmount (currency + amount) as the exact amount to be debited.
- Send instructedAmount with currency only (amount omitted); the bank assigns the exchange rate and computes the credited amount.
- Do not send both debitAmount.amount and instructedAmount.amount.
- If debitAmount is omitted, instructedAmount (currency + amount) is used as the standard same-currency behaviour.
            
### Creditor Agent (Beneficiary Bank)
- If creditorAgent.identification (BIC/bank identifier) is provided, creditorAgent.name and creditorAgent.additionalInformation are optional and may be omitted.
- If creditorAgent.identification is not provided, supply creditorAgent.name and creditorAgent.additionalInformation to identify the beneficiary bank.
            
### Request basics
- Endpoint: POST https://api.bcb.bm/v1/payments/swift
- Authorization: Bearer {token}.
- Accept: application/json (default) or text/csv.
- Idempotency-Key: optional UUID v4 header (≤ 255 chars). See below.
            
### Idempotency
The API supports idempotency through the optional Idempotency-Key header. When supplied, the server caches the successful response and replays it on repeat calls.
- If no idempotency key is provided, the request is processed normally (duplicates are possible).
- If a valid UUID key is supplied, the system stores the response of the first 2xx outcome and replays it on subsequent calls with the same key.
- TTL (cache lifetime): the stored response is retained for a limited window (currently on the order of one hour). After expiry the same key is treated as a new request - but instructionIdentification deduplication still applies for 24 hours. Plan client-side retries to land inside the cache window.
- Scope: keys are partitioned by client/user, HTTP method, and request path. The same key on /payments/swift and /payments/ach-local is not shared - each endpoint has its own cache slot.
- Concurrency: if a second request with the same key arrives while the first is still in flight, the second is rejected with 409 Conflict and message "Request is already being processed." Wait and retry.
- Body mismatch: request bodies are not compared on replay. If you reuse a key with a different body, the original cached response is returned - the new body is ignored. Mint a fresh key for any logically different request.
- Non-2xx responses are not cached. A 4xx validation failure or 5xx server error can be retried with the same key and will execute again.
            
### Deduplication
A separate, business-level guard on the instructionIdentification field, applied independently of the Idempotency-Key header:
- Reusing an instructionIdentification for an active payment is rejected with 409 PAYMENT_DUPLICATE_INSTRUCTION_ID.
- Use a fresh instructionIdentification for each new payment intent. Reuse it (with the same Idempotency-Key) only when retrying the exact same payment.
- The deduplication window is currently configured as 24 hours from the first accepted request.
            
### How Idempotency-Key and instructionIdentification combine
They are independent mechanisms with different purposes.
- Idempotency-Key (header) is a transport-level retry token. It lets you safely retry the same HTTP call and get the original response replayed.
- instructionIdentification (body) is the business identifier of the payment. It is persisted on the payment record and forwarded downstream. To prevent the same payment intent from being submitted twice, a value that is already in flight or recently accepted is rejected with 409 PAYMENT_DUPLICATE_INSTRUCTION_ID (window: 24 hours).
            
| Idempotency-Key | instructionIdentification | Behaviour |
|---|---|---|
| no | no | No protection. Each call creates a new payment. |
| yes | no | HTTP retries of the same call replay the original response. A new Idempotency-Key creates a new payment. |
| no | yes | First call is processed normally. Reusing the same business identifier within 24 hours is rejected with 409 PAYMENT_DUPLICATE_INSTRUCTION_ID. The original success response is not replayed - record it client-side. |
| yes | yes | Recommended. HTTP retries of the same call replay the original response. A new Idempotency-Key reusing an in-flight instructionIdentification is rejected with 409. |
            
### Resilience: classifying responses
The dedupe and idempotency layers together cover three distinct failure modes. The status code tells you what to do next:
            
- 503 DEDUPE_LOCK_UNAVAILABLE - the duplicate-check store could not acquire its lock for instructionIdentification. The payment was not submitted to core banking. Safe to retry after a short backoff with the same instructionIdentification (and the same Idempotency-Key, if you used one). This is not "a duplicate was detected" - it is "we could not verify uniqueness right now."
- 409 PAYMENT_DUPLICATE_INSTRUCTION_ID - this instructionIdentification was already accepted within the 24-hour window. Do not retry the POST; query payment status to reconcile.
- 5xx, connection timeout, or no response - outcome unknown. Retry with the same Idempotency-Key and same instructionIdentification. The server will either replay the original 201 (if the first attempt landed) or return 409 PAYMENT_DUPLICATE_INSTRUCTION_ID (also indicating the first attempt landed).
            
Decision tree in pseudocode:
            
javascript
async function submitPayment(paymentRequest, idempotencyKey) {
  for (let attempt = 1; attempt  keep BOTH values stable; the server will replay or short-circuit safely
retry(intent);
            
// After 409 PAYMENT_DUPLICATE_INSTRUCTION_ID
//   -> do NOT POST again; query status to reconcile
await getPaymentStatus(intent.instructionIdentification);

            
### Idempotency-Key lifecycle (client-side checklist)
- Mint the key before the HTTP call and persist it alongside the payment intent so a process restart or retry can still find it.
- Reuse it for every retry of the same intent; treat it as "spent" only after a terminal (2xx or non-retryable 4xx) response.
- Plan retries to land inside the cache window (~1 hour). Beyond that, instructionIdentification (24 h) is your remaining guard.
            
### Minimal Request Example
            
javascript
const res = await fetch('https://api.bcb.bm/v1/payments/swift', {
  method: 'POST',
  headers: {
    'Authorization':   Bearer ${token},
    'Content-Type':    'application/json',
    'Accept':          'application/json',
    'Idempotency-Key': idempotencyKey, // UUID v4, per payment intent
  },
  body: JSON.stringify(paymentRequest), // shape: see request schema below
});

            
The full request and response schemas, including field types and a worked example, are rendered below from the API contract.

Required Permission: payment-swift

This endpoint requires the permission claim payment-swift to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

## List payment statuses for an account

 - [GET /v1/accounts/{accountNumber}/payments](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/payments/transactionstatus_getaccounttransactionstatuses.md): Retrieves status information for all payments associated with a specific account. This endpoint:
            
- Provides comprehensive payment status details including type, status, transaction ID, external reference, remittance information, amounts, value date, and exchange rate.
- Supports both JSON and CSV response formats based on the Accept header.
- Supports cursor-based pagination for efficient handling of large payment status datasets.

### Pagination
This endpoint uses cursor-based pagination with server-side result-set management:
- First Request: Optionally specify pageSize (default: 100, max: 1000). The server creates a cursor and returns a pageToken.
- Subsequent Requests: Use the pageToken from previous responses with pageStart to navigate pages.
- Page Token: Contains encoded pagination context including pageSize, so don't specify pageSize in subsequent requests.
- Total Pages: Calculate using Math.ceil(total_size / page_size) from the response metadata.

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/accounts/{accountNumber}/payments

### Sample Request in JavaScript

javascript
async function getAllPaymentStatusesPaginated(accountNumber) {
  try {
    let allPaymentStatuses = [];
    let pageStart = 1;
    let pageToken = null;
    let totalPages = 0;

    do {
      // Build URL with pagination parameters
      let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
      const params = new URLSearchParams();
      
      if (pageStart === 1) {
        // First request: specify pageSize
        params.append('pageSize', '100');
      } else {
        // Subsequent requests: use pageToken and pageStart
        params.append('pageToken', pageToken);
        params.append('pageStart', pageStart.toString());
      }
      
      if (params.toString()) {
        url += '?' + params.toString();
      }

      const response = await fetch(url, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(Error: ${errorData.message || 'Unknown error'});
      }

      const data = await response.json();
      console.log(Page ${pageStart} data:, data);

      // Store pagination info from first request
      if (pageStart === 1 && data.meta && data.meta.pagination) {
        pageToken = data.meta.pagination.page_token;
        totalPages = Math.ceil(data.meta.pagination.total_size / data.meta.pagination.page_size);
        console.log(Total pages: ${totalPages}, Page token: ${pageToken});
      }

      // Collect payment statuses from this page
      if (data.data && data.data.length > 0) {
        allPaymentStatuses.push(...data.data);
        console.log(Collected ${data.data.length} payment statuses from page ${pageStart});
      }

      pageStart++;
    } while (pageStart  {
      console.log(Payment ${index + 1}:, payment.transactionId);
      console.log('Type:', payment.type);
      console.log('Status:', payment.status);
      console.log('External Reference:', payment.externalReference);
      console.log('Remittance Information:', payment.remittanceInformation);
      console.log('Value Date:', payment.valueDate);
      console.log('Debit Amount:', ${payment.debitAmount.amount} ${payment.debitAmount.currency});
      if (payment.creditAmount && payment.creditAmount.amount) {
        console.log('Credit Amount:', ${payment.creditAmount.amount} ${payment.creditAmount.currency});
      }
      console.log('-------------------');
    });

    return allPaymentStatuses;
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
    throw error;
  }
}

// Alternative: Get single page of payment statuses
async function getPaymentStatusesPage(accountNumber, pageStart = 1, pageToken = null) {
  try {
    let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
    const params = new URLSearchParams();
    
    if (pageStart === 1 && !pageToken) {
      params.append('pageSize', '50'); // Custom page size
    } else {
      params.append('pageToken', pageToken);
      params.append('pageStart', pageStart.toString());
    }
    
    if (params.toString()) {
      url += '?' + params.toString();
    }

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Error: ${errorData.message || 'Unknown error'});
    }

    const data = await response.json();
    console.log('Payment statuses page:', data);
    return data;
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
    throw error;
  }
}

// Example usage:
getAllPaymentStatusesPaginated('123456789'); // Retrieves all payment statuses across multiple pages
// OR
getPaymentStatusesPage('123456789', 1).then(firstPage => {
  console.log('First page:', firstPage);
  // Use firstPage.meta.pagination.page_token for subsequent requests
});


Required Permission: get-payment-status

This endpoint requires the permission claim get-payment-status to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

## Get payment status

 - [GET /v1/payments/{paymentId}/status](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/payments/transactionstatus_gettransactionstatus.md): Retrieves detailed status information for a specific payment identified by its payment ID (also known as transaction ID). This endpoint provides comprehensive status details including:

- Type: The type of payment (e.g., "Outward Swift Payment MT103 API")
- Status: Current status of the payment (e.g., "Pending", "Completed", "Reversed")
- TransactionId: Unique payment identifier (or Transaction Id)
- ExternalReference: External reference number for the payment
- RemittanceInformation: Free-text information about the purpose of the payment
- DebitAmount: The amount debited from the account, including currency code
- CreditAmount: The amount credited to the account, including currency code
- ValueDate: The date when the payment was/will be processed
- ExchangeRate: The exchange rate applied to the payment

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL:
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/payments/{paymentId}/status

### Sample Request in JavaScript:

javascript
async function getPaymentStatus(paymentId) {
  try {
    const response = await fetch(https://api.bcb.bm/v1/payments/${paymentId}/status, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Error: ${errorData.message || 'Unknown error'});
    }

    const paymentStatus = await response.json();
    console.log('Payment Status Details:');
    console.log('Payment ID:', paymentStatus.transactionId);
    console.log('Type:', paymentStatus.type);
    console.log('Status:', paymentStatus.status);
    console.log('External Reference:', paymentStatus.externalReference);
    console.log('Remittance Information:', paymentStatus.remittanceInformation);
    console.log('Value Date:', paymentStatus.valueDate);
    console.log('Debit Amount:', ${paymentStatus.debitAmount.amount} ${paymentStatus.debitAmount.currency});
    
    if (paymentStatus.creditAmount && paymentStatus.creditAmount.amount) {
      console.log('Credit Amount:', ${paymentStatus.creditAmount.amount} ${paymentStatus.creditAmount.currency});
    }
    
    // Implement business logic based on payment status
    if (paymentStatus.status === 'Completed') {
      console.log('Payment has been successfully completed.');
    } else if (paymentStatus.status === 'Pending') {
      console.log('Payment is still being processed.');
    } else if (paymentStatus.status === 'Failed') {
      console.log('Payment failed. Please check the details or contact support.');
    }
  } catch (error) {
    console.error('There was a problem retrieving the payment status:', error.message);
  }
}

// Example usage:
getPaymentStatus('PAY-001-2023');


Required Permission: get-payment-status

This endpoint requires the permission claim get-payment-status to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.