v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB

Incoming Payments

Reject incoming payment

Reject an incoming payment. Only applies to the following payments:

Asynchronous SEPA instant incoming payments to reject: type = sepa_instant, direction = credit; status = pending_confirmation
- Set the incoming payment status to rejected
SEPA direct debits incoming payments: type = sepa, direction = debit; status = received
- Set the incoming payment status to pending_rejection.

post/incoming_payments/{id}/reject

Path parameters

idstring required

The ID of the incoming payment.

Request body

reasonstring required

Authorised reasons depend on the payment scheme. For SEPA, refer to SEPA reason codes.

Response

200

idstring uuid required

The UUID of the incoming payment.

statusstring required

The lifecycle stage of this incoming payment. It will be updated as the incoming payment is processed.

status_detailsstring required

The details of the status of this incoming payment.

objectstring required

Type of the object, incoming_payment.

idempotency_keystring required

An idempotency key is a unique value sent by the client, which the server uses to recognize subsequent retries of the same request.

reconciliation_status'partially_reconciled' | 'reconciled' | 'unreconciled' | 'excluded' required

The reconciliation status of the incoming payment, which is either unreconciled, reconciled, partially_reconciled, or excluded.

initiated_atstring date-time required

The payment order initiation UTC timestamp with ISO 8601 format to the milliseconds without trailing zeros. Only supported for sepa_instant payments.

reconciled_amountinteger required

The reconciled amount.

created_atstring date-time required

The UTC timestamp of the creation of this incoming payment.

The type of payment.

direction'credit' required

Either credit or debit. Describes the direction the money is flowing. A credit moves money from someone else's account to your account. A debit moves money from your account to someone else's account. An incoming payment of type:sepa and direction:credit is a SEPA Credit Transfer (SCT). An incoming payment of type:sepa and direction:debit is a SEPA Direct Debit (SDD). Only credit is supported for now.

amountinteger required

The absolute amount of a payment, in the specified currency's smallest units. For euro payments, the smallest unit is cents. €20 is represented as 2000.

currency'EUR' required

The three-letter ISO 4217 currency code, in lowercase. Only EUR is supported for now.

connected_account_idstring uuid required

The ID of the connected account that receives the incoming payment.

receiving_account_idstring uuid required

The ID of the internal account that receives the incoming payment.

referencestring required

The reference that will appear on the origin and destination account statements, with a maximum of 140 characters.

value_datestring date required

The value date of the incoming payment.

requested_execution_datestring date required

The requested execution date of the incoming payment.

purposestring

The purpose code of the incoming payment, ensuring compliance with regulatory requirements of certain beneficiary countries. Only applicable to swift and chaps payment types.

category_purpose_codestring

The category purpose of the incoming payment. Recommended for CHAPS payments.

uetrstring uuid

Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI.

direct_debit_mandate_idstring uuid required

The ID of the incoming payment’s direct debit mandate.

direct_debit_sequence_type'first' | 'recurring' | 'final' | 'one_off' nullable required

Identifies the direct debit sequence, such as first, recurrent, final or one-off. This field is optional and should only be used when direct_debit_mandate or direct_debit_mandate_id is provided.

routing_instructionstring

Specific instructions intended for the next financial institution in the payment chain to ensure proper processing of the transaction. Only applicable to swift payments.

instructing_agentstring

When applicable, the instructing agent, or financial institution having sent the incoming payment.

instructed_agentstring

When applicable, the instructed agent, or financial institution having received the incoming payment.

settlement_methodstring

When applicable, the settlement method of the incoming payment, whether instructing_agent, instructed_agent, or cover.

instructing_settlement_agentstring

The instructing settlement agent. Only applicable to swift payments.

instructed_settlement_agentstring

The instructed settlement agent. Only applicable to swift payments.

fee_optionstring

Network payment fee preference. Only applicable to Swift payments such as originator (fee beared by the originating party), receiver (fee beared by the receiving party), or shared (fee split between the originating and the receiving parties).

fi_to_fi_option'advi' | 'core' | 'cover'

Filled for incoming payments with type = swift_fi_to_fi or target2_fi_to_fi.

related_payment_idstring uuid

Auto-filled for incoming payments with type = swift_fi_to_fi or target2_fi_to_fi and fi_to_fi_option = cover. If no related payment can be found by our system related_payment_id, and consequently related_payment_type, will be empty. In this case related_payment will contain data about the related payment.

related_payment_typestring

The type of the related payment. Only filled when related_payment_id could be determined by our system.

related_paymentobject

See related_payment_id for details about when this property is present. If it's present, it will have the same properties as it's encompassing object (incoming payment).

metadataobject required

Additional client data in JSON format. See Metadata.

Example response

{
  "status": "sent",
  "object": "incoming_payment",
  "idempotency_key": "8A2gcC",
  "bank_data": {
    "file_id": "a815e756-5576-4d40-9fbd-38ec304b856c",
    "message_id": "1gXrtKMxLJ",
    "transaction_id": "1zDrzOMxCJ",
    "end_to_end_id": "c3b2d737bc"
  },
  "reconciliation_status": "partially_reconciled",
  "initiated_at": "2024-04-12T14:23:45.123Z",
  "reconciled_amount": 1500,
  "type": "sepa",
  "direction": "credit",
  "amount": 3000,
  "currency": "EUR",
  "originating_account": {
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "fi_bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "holder_address": {
      "building_number": "1",
      "street_name": "rue de l'Abondance",
      "postal_code": "69003",
      "region_state": "Ile-de-France",
      "city": "Lyon",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    },
    "bank_name": "BankCo",
    "bank_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    },
    "creditor_identifier": "FR12ZZZ123456",
    "organization_identification": {
      "legal_entity_identifier": "529900T8BM49AURSDO55",
      "business_identification_code": "SOGEFRPP",
      "others": [
        {
          "value": "123456789123"
        }
      ]
    },
    "private_identification": {
      "birth_date": "1990-01-01",
      "birth_city": "Paris",
      "birth_country": "FR",
      "other": {
        "identification": "123456789",
        "identification_type": "passport_number"
      }
    }
  },
  "receiving_account": {
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "fi_bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "holder_address": {
      "building_number": "1",
      "street_name": "rue de l'Abondance",
      "postal_code": "69003",
      "region_state": "Ile-de-France",
      "city": "Lyon",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    },
    "bank_name": "BankCo",
    "bank_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    },
    "organization_identification": {
      "legal_entity_identifier": "529900T8BM49AURSDO55",
      "business_identification_code": "SOGEFRPP",
      "others": [
        {
          "value": "123456789123"
        }
      ]
    },
    "private_identification": {
      "birth_date": "1990-01-01",
      "birth_city": "Paris",
      "birth_country": "FR",
      "other": {
        "identification": "123456789",
        "identification_type": "passport_number"
      }
    }
  },
  "ultimate_originator": {
    "holder_name": "SoftwareCo",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    },
    "organization_identification": {
      "legal_entity_identifier": "529900T8BM49AURSDO55",
      "business_identification_code": "SOGEFRPP",
      "others": [
        {
          "value": "123456789123"
        }
      ]
    },
    "private_identification": {
      "birth_date": "1990-01-01",
      "birth_city": "Paris",
      "birth_country": "FR",
      "other": {
        "identification": "123456789",
        "identification_type": "passport_number"
      }
    }
  },
  "ultimate_receiver": {
    "holder_name": "SoftwareCo",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    },
    "organization_identification": {
      "legal_entity_identifier": "529900T8BM49AURSDO55",
      "business_identification_code": "SOGEFRPP",
      "others": [
        {
          "value": "123456789123"
        }
      ]
    },
    "private_identification": {
      "birth_date": "1990-01-01",
      "birth_city": "Paris",
      "birth_country": "FR",
      "other": {
        "identification": "123456789",
        "identification_type": "passport_number"
      }
    }
  },
  "reference": "Invoice 1234",
  "structured_reference": [
    {
      "creditor_reference_information": {
        "type": {
          "code": "dispatch_advice",
          "issuer": "Issuer"
        },
        "reference": "RF18539007547034"
      },
      "referred_document_information": [
        {
          "type": {
            "code": "commercial_invoice",
            "issuer": "Issuer"
          },
          "number": "ABC-13679",
          "related_date": "2024-03-15"
        }
      ],
      "invoicer": {
        "name": "Invoicer name"
      },
      "invoicee": {
        "name": "Invoicee name"
      },
      "additional_remittance_info": [
        "Payment for invoice INV-2024-001"
      ]
    }
  ],
  "purpose": "SALA",
  "category_purpose_code": "B2B",
  "direct_debit_mandate": {
    "reference": "REF-783232",
    "sequence": "recurring",
    "frequency": "recurring"
  },
  "direct_debit_sequence_type": "recurring",
  "intermediary_agents": [
    {
      "financial_institution_identification": {
        "swift_code": "SOMEBIC0XXX",
        "bank_code": "SOMEBIC0XXX",
        "bank_code_format": "bic",
        "name": "Bank A",
        "legal_entity_identifier": "219200WSGIIZEPF1P999",
        "postal_address": {
          "line_1": "1, place de la Concorde",
          "building_number": "1",
          "street_name": "place de la Concorde",
          "postal_code": "75008",
          "city": "Paris",
          "country": "FR",
          "department": "Marketing",
          "sub_department": "Content team",
          "building_name": "Bat. 4",
          "floor": "3",
          "postal_box": "67b",
          "room": "47",
          "city_location_name": "Confluences",
          "district_name": "District 9"
        },
        "other": {
          "identification": "35664632",
          "custom_identification_type": "custom_type",
          "identification_issuer": "HMRC"
        }
      },
      "account_number": "GB7601234567890627967100010",
      "account_number_format": "iban",
      "organization_identification": {
        "name": "Bank A",
        "bank_code": "SOMEBIC0XXX",
        "legal_entity_identifier": "219200WSGIIZEPF1P999",
        "other": "35664632"
      },
      "postal_address": {
        "line_1": "1, place de la Concorde",
        "building_number": "1",
        "street_name": "place de la Concorde",
        "postal_code": "75008",
        "city": "Paris",
        "country": "FR",
        "department": "Marketing",
        "sub_department": "Content team",
        "building_name": "Bat. 4",
        "floor": "3",
        "postal_box": "67b",
        "room": "47",
        "city_location_name": "Confluences",
        "district_name": "District 9"
      }
    }
  ],
  "previous_instructing_agents": [
    {
      "financial_institution_identification": {
        "swift_code": "SOMEBIC0XXX",
        "bank_code": "SOMEBIC0XXX",
        "bank_code_format": "bic",
        "name": "Bank A",
        "legal_entity_identifier": "219200WSGIIZEPF1P999",
        "postal_address": {
          "line_1": "1, place de la Concorde",
          "building_number": "1",
          "street_name": "place de la Concorde",
          "postal_code": "75008",
          "city": "Paris",
          "country": "FR",
          "department": "Marketing",
          "sub_department": "Content team",
          "building_name": "Bat. 4",
          "floor": "3",
          "postal_box": "67b",
          "room": "47",
          "city_location_name": "Confluences",
          "district_name": "District 9"
        },
        "other": {
          "identification": "35664632",
          "custom_identification_type": "custom_type",
          "identification_issuer": "HMRC"
        }
      },
      "account_number": "12345678",
      "account_number_format": "iban",
      "organization_identification": {
        "name": "Bank A",
        "bank_code": "SOMEBIC0XXX",
        "legal_entity_identifier": "219200WSGIIZEPF1P999",
        "other": "35664632"
      },
      "postal_address": {
        "line_1": "1, place de la Concorde",
        "building_number": "1",
        "street_name": "place de la Concorde",
        "postal_code": "75008",
        "city": "Paris",
        "country": "FR",
        "department": "Marketing",
        "sub_department": "Content team",
        "building_name": "Bat. 4",
        "floor": "3",
        "postal_box": "67b",
        "room": "47",
        "city_location_name": "Confluences",
        "district_name": "District 9"
      }
    }
  ],
  "routing_instruction": "Cross-border routing instructions",
  "payment_validation": {
    "validation_results": [
      {
        "payment_validation_rule_id": "c2c303de-c0f0-4015-801d-6ae24f248092",
        "validations": [
          [
            {
              "status_details": "some details",
              "resource_id": "b29b85ad-b2ef-4978-b27f-e44ae4914756",
              "resource_url": "https://example.com/b29b85ad-b2ef-4978-b27f-e44ae4914756",
              "last_updated_at": "2022-01-03T11:53:19.568Z",
              "retry_details": {
                "attempt_count": 1,
                "max_attempts": 3,
                "next_attempt_at": "2026-03-27T14:00:00Z",
                "final_action": "reject_payment"
              }
            }
          ]
        ]
      }
    ]
  },
  "cbs_data": {
    "transaction_id": "c2c303de-c0f0-4015-801d-6ae24f248092",
    "authorization_id": "62f87f47-86c6-4b1e-b49d-e6df91922cd7",
    "transactions": [
      {
        "id": "c2c303de-c0f0-4015-801d-6ae24f248092",
        "type": "withdrawal",
        "context": "deposit",
        "authorization_id": "62f87f47-86c6-4b1e-b49d-e6df91922cd7",
        "channel": "cash",
        "booked_at": "2022-01-03T11:53:19.568Z"
      }
    ]
  },
  "settlement_method": "cover",
  "fi_to_fi_option": "core",
  "related_payment_id": "a815e756-5576-4d40-9fbd-38ec304b856c",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  }
}