# SWIFT Payment

Initiates a SWIFT payment transfer. The request must include all required payment details including:
- Source and destination account information
- Payment amount and currency
- Beneficiary details
- Payment purpose and reference information
            
### Key Features:
- Supports international wire transfers via SWIFT network
- Implements idempotency to prevent duplicate transactions
- Validates payment requests before processing
- Supports both JSON and CSV response formats

### 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.
            
### 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/swift
    
### Idempotency
The API supports idempotency through the optional Idempotency-Key header:
- If no idempotency key is provided, the request is processed normally (duplicates are possible)
- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results
- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response
- Idempotency keys are user-specific - different users with the same keys don't share cached responses
- The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000").

### Sample Request in JavaScript:

javascript
async function processSwiftPayment() {
  try {
    const response = await fetch('https://api.bcb.bm/v1/payments/swift', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional: UUID format required if provided
      },
      body: JSON.stringify({
        instructionIdentification: "PAYMENT-123456", // Optional
        debtorAccount: {
          identification: "DEBTOR-ACC-123"
        },
        instructedAmount: {
          currency: "USD",
          amount: "1000.00"
        },
        creditorAccount: {
          identification: "CREDITOR-ACC-456",
          name: "John Doe",
          additionalInformation: ["Additional details"]
        },
        creditorAgent: {
          identification: "BANKBIC123",
          // Optional when a BIC/bank identifier is provided:
          // name: "Beneficiary Bank",
          // additionalInformation: ["SWIFT/BIC code"]
        },
        chargesType: "OUR",
        remittanceInformation: ["Payment for services"]
      })
    });

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

    const result = await response.json();
    
    // Check payment status
    if (result.status === 'success') {
      console.log('Payment processed successfully');
      
      // Log payment details
      console.log('Payment ID:', result.id);
      console.log('Transaction Status:', result.transactionStatus);
      console.log('Unique Identifier:', result.uniqueIdentifier);
      
      // Process payment details
      const details = result.details;
      console.log('External Reference:', details.extReference);
      console.log('Instructed Amount:', details.instructedAmount.amount, details.instructedAmount.currency);
      
      // Process account information
      console.log('Debtor Account:', details.debtorAccount.identification);
      console.log('Creditor Account:', details.creditorAccount.identification);
      console.log('Beneficiary Account:', details.beneficiaryAccount.identification);
      
      // Process settlement details
      const settlement = details.settlementDetails;
      console.log('Amount Credited:', settlement.amountCredited.amount, settlement.amountCredited.currency);
      console.log('Amount Debited:', settlement.amountDebited.amount, settlement.amountDebited.currency);
      console.log('Value Date:', settlement.valueDate);
      console.log('Record Status:', settlement.recordStatus);
      
      // Process charge details
      const charges = details.chargeDetails;
      console.log('Charges Type:', charges.chargesType);
      console.log('Total Charges:', charges.chargeAmount.amount, charges.chargeAmount.currency);
      
      // Process charge analysis
      const chargeAnalysis = charges.chargeAnalysis;
      console.log('Sender Charges:', chargeAnalysis.sender.amount, chargeAnalysis.sender.currency);
      console.log('Receiver Charges:', chargeAnalysis.receiver.amount, chargeAnalysis.receiver.currency);
      
      // Process beneficiary information
      console.log('Beneficiary Name:', details.beneficiary.name);
      console.log('Beneficiary Bank:', details.beneficiaryAgent.name);
      
      // Process remittance information
      if (details.remittanceInformation) {
        console.log('Remittance Information:');
        details.remittanceInformation.forEach(info => console.log('-', info));
      }
      
      // Process linked activities
      if (result.linkedActivities && result.linkedActivities.length > 0) {
        console.log('Linked Activities:');
        result.linkedActivities.forEach(activity => {
          console.log('- Activity ID:', activity.id);
          console.log('  Status:', activity.status);
          console.log('  Transaction Status:', activity.transactionStatus);
          console.log('  Unique Identifier:', activity.uniqueIdentifier);
        });
      }
    } else {
      console.error('Payment processing failed:', result.status);
      // Handle failed payment
      if (result.details) {
        console.error('Error details:', result.details);
      }
    }
  } catch (error) {
    console.error('Error:', error);
    // Handle error appropriately
  }
}

// Example usage:
processSwiftPayment();


### Response Structure

| Field | Type | Description |
|-------|------|-------------|
| id | string | Unique identifier for the payment |
| status | string | Payment status (success or failed) |
| transactionStatus | string | Detailed transaction status |
| uniqueIdentifier | string | Unique identifier for tracking |
| details | object | Payment details object |
| linkedActivities | array | Related financial activities |

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.

Endpoint: POST /v1/payments/swift
Version: v1
Security: Authorization, Feature Permissions

## Request fields (application/json):

  - `instructionIdentification` (string,null)
    Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.

  - `debtorAccount` (object, required)
    Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.

  - `debtorAccount.identification` (string, required)
    Unique identification of the account, such as an Bank Account Number
or a local account number.

  - `instructedAmount` (object, required)
    Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

  - `instructedAmount.currency` (string, required)
    Currency ISO code

  - `instructedAmount.amount` (string, required)
    Amount

  - `creditorAccount` (object, required)
    Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.

  - `creditorAccount.identification` (string, required)
    Unique identification of the party, such as a BIC (Bank Identifier Code) for financial institutions
or an account number for account holders.

  - `creditorAccount.name` (string,null)
    Name by which the party is known and which is usually used to identify the party.

  - `creditorAccount.additionalInformation` (array,null)
    Additional information about the party that may be required for processing the payment,
such as address details, country codes, or specific payment instructions.
Max 4 lines; each line max 35 characters.

  - `creditorAgent` (object, required)
    Financial institution servicing an account for the creditor.

  - `intermediaryAgent` (object,null)
    Agent between the debtor's agent and the creditor's agent.

  - `chargesType` (string, required)
    Specifies which party/parties will bear the charges associated with the processing of the payment transaction.
Max length: 3 characters (e.g., OUR/SHA/BEN).

  - `remittanceInformation` (array, required)
    Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle.
Limit: up to 4 lines; each line max 35 characters.

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique identifier assigned by the bank for the SWIFT transfer.
This ID can be used for future reference and tracking of the payment.

  - `status` (string, required)
    The current status of the payment processing.
Possible values include:
- success: Payment has been accepted for processing
- failed: Payment failed

  - `transactionStatus` (string, required)
    Detailed transaction status indicating the current state of the transfer.
This provides more granular status information than the main status field.

  - `uniqueIdentifier` (string, required)
    A unique identifier specific to this instance of the SWIFT transfer.
This identifier remains constant throughout the lifecycle of the payment
and can be used for reconciliation purposes.

  - `details` (object, required)
    Detailed information about the payment transaction including
amounts, accounts, and settlement information.

  - `details.extReference` (string, required)
    External reference number assigned by the bank's payment processing system.
This reference can be used for tracking and reconciliation purposes.

  - `details.instructedAmount` (object, required)
    The amount and currency of the payment as instructed by the payment initiator.
This represents the original payment amount before any charges or conversions.

  - `details.instructedAmount.currency` (string, required)
    Currency ISO code

  - `details.instructedAmount.amount` (string, required)
    Amount

  - `details.debtorAccount` (object, required)
    Reference information for the account from which the payment is debited.
Includes the account identifier and scheme information.

  - `details.debtorAccount.schemeName` (string,null)
    The name of the identification scheme, e.g. "BBAN", "AccountNumber".

  - `details.debtorAccount.identification` (string, required)
    The identifier within that scheme (e.g. account number).

  - `details.debtorAccount.Name` (string, required)
    The name of the account, if available (optional).

  - `details.beneficiaryAccount` (object, required)
    Reference information for the beneficiary's account.
This may differ from the creditor account in certain scenarios.

  - `details.creditorAccount` (object, required)
    Reference information for the account to be credited with the payment.
This represents the immediate recipient account of the funds.

  - `details.settlementDetails` (object, required)
    Details about the settlement of the payment, including credited and
debited amounts, value dates, and settlement status.

  - `details.settlementDetails.amountCredited` (object, required)
    The amount that was credited to the beneficiary account.
This may differ from the instructed amount due to currency conversion
or intermediary bank charges.

  - `details.settlementDetails.amountDebited` (object, required)
    The total amount debited from the sender's account.
This includes the payment amount plus any applicable charges.

  - `details.settlementDetails.valueDate` (string, required)
    The date on which the payment is settled between banks.
This is the date when the funds become available to the beneficiary.
Format: ISO 8601 date string (YYYY-MM-DD)

  - `details.settlementDetails.recordStatus` (string, required)
    The current status of the settlement record.

  - `details.chargeDetails` (object, required)
    Information about the charges applied to the payment, including
charge type, amounts, and the account to which charges are applied.

  - `details.chargeDetails.chargesType` (string, required)
    Specifies how the charges for the payment are allocated.
Possible values:
- OUR: All charges are paid by the sender
- BEN: All charges are paid by the beneficiary
- SHA: Charges are shared between sender and beneficiary

  - `details.chargeDetails.chargeAmount` (object, required)
    The total amount of charges applied to the payment.
Includes both sending and receiving bank charges.

  - `details.chargeDetails.chargeAccount` (object, required)
    Reference information for the account from which charges are collected.
This may be different from the main debit account.

  - `details.chargeDetails.chargeAnalysis` (object, required)
    Detailed breakdown of how charges are distributed between
the sending and receiving parties.

  - `details.chargeDetails.chargeAnalysis.sender` (object, required)
    The amount of charges applied by and payable to the sending bank.
This may include processing fees, wire transfer fees, or other sending bank charges.

  - `details.chargeDetails.chargeAnalysis.receiver` (object, required)
    The amount of charges applied by and payable to the receiving bank.
This may include processing fees, incoming wire fees, or other receiving bank charges.

  - `details.remittanceInformation` (array,null)
    Collection of unstructured information provided with the payment
to help with reconciliation and payment identification.

  - `details.remittanceInformation.unstructured` (string, required)
    The narrative text (e.g. remittance line, beneficiary note, etc.).

  - `details.beneficiary` (object, required)
    Detailed information about the ultimate beneficiary of the payment.
Includes identification, name, and additional information.

  - `details.beneficiary.identification` (string, required)
    Unique identification of the party, such as a BIC (Bank Identifier Code) for financial institutions
or an account number for account holders.

  - `details.beneficiary.name` (string,null)
    Name by which the party is known and which is usually used to identify the party.

  - `details.beneficiary.additionalInformation` (array,null)
    Additional information about the party that may be required for processing the payment,
such as address details, country codes, or specific payment instructions.
Max 4 lines; each line max 35 characters.

  - `details.beneficiaryAgent` (object, required)
    Information about the beneficiary's bank or financial institution.
Typically, includes the BIC/SWIFT code and bank details.

  - `details.intermediaryAgent` (object, required)
    Details of any intermediary bank involved in the payment chain.
This is optional and only present for payments requiring intermediary processing.

  - `linkedActivities` (array, required)
    Collection of related financial activities associated with this payment.
This may include charges, forex conversions, or other related transactions.

  - `linkedActivities.id` (string, required)
    The unique identifier for the activity.

  - `linkedActivities.transactionStatus` (string, required)
    The current processing status of the transaction.

  - `linkedActivities.status` (string, required)
    The general status of the activity.

  - `linkedActivities.uniqueIdentifier` (string,null)
    A unique identifier specific to this instance of the activity.

  - `linkedActivities.activityDetails` (object, required)
    Detailed information about the activity.

  - `linkedActivities.activityDetails.arrangementId` (string, required)
    Unique identifier for the arrangement associated with this activity.

  - `linkedActivities.activityDetails.activityId` (string, required)
    Identifier for the type of activity.

  - `linkedActivities.activityDetails.productId` (string, required)
    Product identifier related to the activity.

  - `linkedActivities.activityDetails.currencyId` (string, required)
    Currency code for the activity.

  - `linkedActivities.activityDetails.effectiveDate` (string, required)
    Date when the activity becomes effective.

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 403 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 500 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition