Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
Payment Orders

Cancel payment order

Cancel a payment order. A payment order can be canceled from the pending_approval and approved statuses. Canceling a payment orders updates its status to canceled.

Cancel payment orders in batches using the Bulk actions object.

post/payment_orders/{id}/cancel

Path parameters

idstring required

The ID of the payment order.

Request body

reasonstring

Reason code for the cancelation. Only used when canceling SEPA direct debit payment orders before settlement.

Example request

{
  "reason": "DUPL"
}

Response

200

idstring uuid required

The UUID of the payment order.

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.

objectstring required

Type of the object, payment_order.

type'ae_aani' | 'ae_uaefts' | 'ae_uaefts_rtgs' | 'ar_coelsa' | 'ar_mep' | 'ar_transfer_30' | 'au_becs' | 'au_npp' | 'au_rits' | 'bacs' | 'becs' | 'bh_benefit' | 'bh_fawri' | 'bh_rtgs' | 'br_pix' | 'br_str' | 'br_ted' | 'ca_eft' | 'ca_lynx' | 'ca_rtr' | 'cbs_transfer' | 'ch_sct' | 'ch_sic' | 'ch_sip' | 'chaps' | 'cl_cca' | 'cl_lbtr' | 'cl_tef' | 'co_ach' | 'co_bre_b' | 'co_cud' | 'fps' | 'icelandic_exp' | 'id_bifast' | 'id_birtgs' | 'id_sknbi' | 'internal_transfer' | 'ke_eft' | 'ke_pesalink' | 'ke_rtgs' | 'mx_spei' | 'my_duitnow' | 'my_ibg' | 'my_rentas' | 'no_nbo' | 'no_nics' | 'no_nics_instant' | 'osko' | 'ph_instapay' | 'ph_pddts' | 'ph_philpass' | 'pl_elixir' | 'pl_express_elixir' | 'pl_sorbnet' | 'rits' | 'ro_regis' | 'ro_sent' | 'ro_sent_instant' | 'sa_sarie' | 'sa_sarie_instant' | 'sa_sarie_rtgs' | 'se_bankgirot' | 'se_rix' | 'se_rix_instant' | 'sepa' | 'sepa_instant' | 'sepa_urgent' | 'sg_giro' | 'sg_meps' | 'sg_paynow' | 'swift' | 'swift_fi_to_fi' | 'target2' | 'target2_fi_to_fi' | 'th_bahtnet' | 'th_nitmx' | 'th_promptpay' | 'tl_ips' | 'tl_rtimor_ach' | 'tl_rtimor_rtgs' | 'treasury' | 'us_ach' | 'us_fednow' | 'us_rtp' | 'us_wire' | 'za_eft' | 'za_rpp' | 'za_samos' required

The type of payment.

direction'credit' | 'debit' required

The direction of the payment. Describes the direction the money is flowing. A credit moves money from your account to someone else's account. A debit moves money from someone else's account to your account.

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.

value_datestring date required

The value date of the payment order.

statusstring required

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

status_detailsstring required

The details of the status of this payment order.

reconciled_amountinteger required

The reconciled amount.

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

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

referencestring required

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

end_to_end_idstring

The end-to-end ID of the payment order. Only supported for specific banks and payment schemes. Contact us to get more details.

connected_account_idstring uuid required

The ID of the connected account. The connected account is the account used to trigger the payment order.

originating_account_idstring uuid

The ID of the internal_account sending the payment instruction. This attribute is for financial institution customers only, and should be used with Internal accounts of type “own”.

receiving_account_idstring uuid

The ID of the external_account receiving the payment instruction.

direct_debit_mandate_idstring uuid

The mandate's ID authorizing the direct debit. This attribute is filled only when the payment order's direction is debit.

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

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.

uetrstring uuid

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

purposestring

The purpose code of the 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 payment. Recommended for CHAPS payments.

fee_option'originator' | 'receiver' | 'shared'

Network payment fee preference. Only applicable to Swift payments. Supported values include originator (fee paid by the originating party), receiver (paid by the receiving party), or shared (fee split between the originating and the receiving party).

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.

requested_execution_datestring date

The requested execution date of the payment order.

auto_approvalboolean required

The auto_approval flag determines whether a payment requires human intervention before execution.

When true: The system bypasses all manual approval steps.

  • If a validation rule applies, the payment starts as pending_approval.
  • If no rules apply, the payment is immediately approved.

When false: The payment always starts as pending_approval and requires a manual user action. If a validation rule is also attached, it must be successfully completed before the payment can reach the final approved status.

treasury_option'local' | 'international' | 'relocated' | 'safeguarding'

The treasury_option attribute is used to specify the type of treasury payments (type = treasury). It can take the following values, local (for instance payments from a French account to another French internal account), international (French to German accounts), relocated (to send payments from another partner bank), and safeguarding (only applicable to financial institutions, to send funds from their settlement account to their safeguarding account and vice versa).

confidentiality_option'payroll'

Used in case of a confidential payment. Only payroll confidential payments are supported for now.

settlement_method'cover' | 'instructed_agent' | 'instructing_agent'

The settlement_method attribute is mandatory when creating Swift payment orders (type = swift) with a connected account of type financial_institution. For all other payment orders, this attribute - if provided - is simply ignored when creating bank files.

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

The fi_to_fi_option attribute is mandatory when creating payment orders with type = swift_fi_to_fi or target2_fi_to_fi.

related_payment_idstring uuid

Mandatory when creating payment orders with type = swift_fi_to_fi or target2_fi_to_fi and fi_to_fi_option = cover.

related_payment_typestring

Auto-filled based on the related_payment_id.

metadataobject required

Additional client data in JSON format. See Metadata.

custom_fieldsCommonCustomFields required

Custom fields in JSON key:value format. See Custom fields.

initiated_atstring date-time

The UTC timestamp this payment order was initiated. This value marks the start of the payment order lifecycle and has millisecond precision (up to 3 digits where trailing zeros are dropped).<br><br>This field is optional when the payment type is sepa_instant and the connected account type is financial_institution. If included in the request, its value will be reflected in the response. If omitted when optional, the response will include the field with its value defaulting to the current timestamp. In all other scenarios, the field in the response will be null.

instructed_agentstring nullable

Instructed agent of the payment order. Can only be set for financial institution payments of type sepa_instant, target2, and target_2_fi_to_fi. If not set, Mambu Payments will fill this value automatically based on the payment's target scheme or receiving account.

addressee_bank_codestring nullable

Addressee BIC of the payment order. Can only be set for financial institution payments of type sepa_instant, target2, and target_2_fi_to_fi. If not set, Mambu Payments will fill this value automatically based on the payment's target scheme or receiving account.

created_atstring date-time required

The UTC timestamp of the creation of this payment order.

Example response

{
  "id": "b69837bf-e784-4bd1-b0d0-2ad0e61a89b6",
  "idempotency_key": "8A2gcC",
  "object": "payment_order",
  "type": "sepa",
  "direction": "credit",
  "amount": 2000,
  "currency": "EUR",
  "value_date": "2022-01-03",
  "status": "executed",
  "reconciled_amount": 2000,
  "reconciliation_status": "reconciled",
  "reference": "Invoice 1234",
  "end_to_end_id": "c3b2d737bc",
  "connected_account_id": "254e3100-afd6-44f2-8084-87e8ae67b554",
  "originating_account": {
    "account_number": "FR7601234567890627967100010",
    "account_number_format": "iban",
    "bank_code": "SOGEFRPP",
    "bank_code_format": "bic",
    "fi_bank_code": "SOGEFRPP",
    "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"
    },
    "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"
      }
    }
  },
  "originating_account_id": "8d97ed83-a6f7-4929-8e90-01b2912fb6a7",
  "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"
      }
    }
  },
  "receiving_account": {
    "account_number": "FR7601234567891127967100082",
    "account_number_format": "iban",
    "bank_code": "BNPAFRPPXXX",
    "bank_code_format": "bic",
    "fi_bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "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"
    },
    "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"
      }
    }
  },
  "receiving_account_id": "b38f5318-a389-4278-9cbe-d16116750982",
  "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"
      }
    }
  },
  "direct_debit_mandate": {
    "reference": "regmedia-mandate-rz47ash4",
    "signature_date": "2022-01-20",
    "type": "sepa_core",
    "sequence": "recurring",
    "frequency": "recurring"
  },
  "direct_debit_mandate_id": "15ee5994-9019-478c-b27a-a4edfec17c58",
  "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"
      }
    }
  ],
  "swift_gpi": {
    "confirmed_amount": 3000,
    "confirmed_currency": "EUR",
    "tracking_progress": [
      {
        "id": "01",
        "status_details": "G005",
        "bank_code": "SOMEBIC0XXX",
        "fee_amount": 3000,
        "fee_currency": "EUR"
      }
    ]
  },
  "purpose": "SALA",
  "category_purpose_code": "B2B",
  "fee_option": "shared",
  "routing_instruction": "Cross-border routing instructions",
  "requested_execution_date": "2022-01-03",
  "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"
      }
    ]
  },
  "retry_details": {
    "payment_retry_rule_id": "5075f0d2-6a6b-49ea-ae63-b11368873157",
    "original_payment_id": "10384f4e-3eef-42a3-bc8d-8d2f35eb279d",
    "retried_from_payment_id": "8e91531e-c29c-4e69-ab94-71e04f8d0b55",
    "retried_to_payment_id": "58ebd65d-bc3c-4d91-816e-5a011702acbc",
    "retry_scheduled_at": "2024-05-31T15:42:07.314159Z"
  },
  "treasury_option": "local",
  "confidentiality_option": "payroll",
  "settlement_method": "cover",
  "settlement_information": {
    "settlement_account": "FR7630006000011234567890189"
  },
  "fi_to_fi_option": "core",
  "related_payment_id": "a815e756-5576-4d40-9fbd-38ec304b856c",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  },
  "bank_data": {
    "file_id": "a815e756-5576-4d40-9fbd-38ec304b856c",
    "message_id": "1gXrtKMxLJ",
    "transaction_id": "1zDrzOMxCJ",
    "end_to_end_id": "c3b2d737bc"
  },
  "initiated_at": "2022-01-03T11:53:19.568Z",
  "instructed_agent": "SOMEBIC0XXX",
  "addressee_bank_code": "SOMEBIC0XXX",
  "created_at": "2022-01-03T11:53:19.734182Z"
}