# Payments ## API endpoints {% hint style="success" %} Authentication: endpoints listed in this page *require* [header authentication](https://docs.powens.com/api-reference/overview/authentication) with a *service token* with the relevant `payments:*` scope. {% endhint %} ## List payments `GET` `https://{domain}.biapi.pro/2.0/payments` By default, payments are ordered by `register_date`. #### Query Parameters | Name | Type | Description | | --------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | show\_sensitive | Boolean | Set to true to return sensitive fields from identities. Defaults to false. | | limit | Integer | Limit the number of results. | | offset | Integer | First result offset. | | reverse | Boolean | Reverse the results order (by date). | | filter | String | Specify the date field to use when using `min_date` and `max_date` filters. Value can be `register_date` or `validate_date` | | min\_date | Date | Minimal date (inclusive). | | max\_date | Date | Maximal date (exclusive). | | connector\_uuid | String | Filter by connector UUID. `null` can be used to filter payments without an associated connector. | | id\_connector | Integer | Filter by connector ID. `null` can be provided to filter payments without an associated connector. | | id\_connector\_source | Integer | Filter by connector source ID. | | state | String | Filter by [`state`](#payment-object). | | error\_code | String | Filter by [`error_code`](#payment-object). | | bank\_payment\_id | String | Filter by bank payment ID. | | website | String | Filter by website field value. | | payer\_identification | String | Filter by [`payer.identification`](#paymentaccount-object). | | beneficiary\_identification | String | Filter by [`beneficiary.identification`](#paymentaccount-object). | | reference\_id | String | Filter by instruction reference ID | | execution\_date\_type | String | Filter by[`execution_date`](#executiondate-values) | | order\_by | String | Order the payments by the specified field. Value can be `id`, `register_date`, `validate_date`, `state`, `connectors`, `amount`, `instruction_count`, `execution_date_type`. | | country | String | Filter by country. Several countries can be provided, separated by commas. | {% tabs %} {% tab title="200: OK List of payments" %} Response body: [#paymentlistresponse-object](#paymentlistresponse-object "mention") {% endtab %} {% endtabs %} ## Create a payment `POST` `https://{domain}.biapi.pro/2.0/payments` For more information on the full payment initiation and validation flow, see [this guide](https://docs.powens.com/documentation/integration-guides/pay/initiating-a-one-time-payment-with-the-webview). Request body: [#paymentinitrequest-object](#paymentinitrequest-object "mention") #### Query Parameters | Name | Type | Description | | --------------- | ------- | -------------------------------------------------------------------------- | | show\_sensitive | Boolean | Set to true to return sensitive fields from identities. Defaults to false. | {% tabs %} {% tab title="200: OK Payment created" %} Response body: [#payment-resource](#payment-resource "mention") {% endtab %} {% endtabs %} ## Get a payment `GET` `https://{domain}.biapi.pro/2.0/payments/{paymentId}` This endpoint should only be used for getting a payment's status on redirect, not for polling; see [this section of the initiation and validation guide](https://docs.powens.com/documentation/integration-guides/pay/initiating-a-one-time-payment-with-the-webview#get-the-payment-status) for more information. #### Query Parameters | Name | Type | Description | | --------------- | ------- | -------------------------------------------------------------------------- | | show\_sensitive | Boolean | Set to true to return sensitive fields from identities. Defaults to false. | {% tabs %} {% tab title="200: OK Payment exists" %} Response body: [#payment-resource](#payment-resource "mention") {% endtab %} {% endtabs %} ## Update, validate or cancel a payment `POST` `https://{domain}.biapi.pro/2.0/payments/{paymentId}` This is used in the following flows: :heavy\_minus\_sign: [Cancelling a payment](https://docs.powens.com/documentation/integration-guides/pay/cancelling-a-payment)\ :heavy\_minus\_sign: [Implementing your own payment validation webview (advanced)](https://docs.powens.com/documentation/integration-guides/pay/advanced/implementing-your-own-payment-validation-webview) Request body: one of the following objects. :heavy\_minus\_sign:[#paymentvalidaterequest-object](#paymentvalidaterequest-object "mention")\ :heavy\_minus\_sign:[#paymentresumerequest-object](#paymentresumerequest-object "mention")\ :heavy\_minus\_sign:[#paymentsubmitfieldvaluesrequest-object](#paymentsubmitfieldvaluesrequest-object "mention")\ :heavy\_minus\_sign:[#paymentsubmitpsuvalidationrequest-object](#paymentsubmitpsuvalidationrequest-object "mention")\ :heavy\_minus\_sign:[#paymentconfirmrequest-object](#paymentconfirmrequest-object "mention")\ :heavy\_minus\_sign:[#paymentcancelrequest-object](#paymentcancelrequest-object "mention") #### Query Parameters | Name | Type | Description | | --------------- | ------- | -------------------------------------------------------------------------- | | show\_sensitive | Boolean | Set to true to return sensitive fields from identities. Defaults to false. | {% tabs %} {% tab title="200: OK Payment updated" %} Response body: [#payment-resource](#payment-resource "mention") {% endtab %} {% endtabs %} ## Generate a payment-scoped token `POST` `https://{domain}.biapi.pro/2.0/payments/{paymentId}/scopedtoken` This endpoint **requires** a payment token with the scope `payments:validate`. Request body: [#paymenttokenrequest-object](#paymenttokenrequest-object "mention") {% tabs %} {% tab title="200: OK Token issued" %} Response body: [#paymenttokenresponse-object](#paymenttokenresponse-object "mention") {% endtab %} {% endtabs %} Note that using the `show_sensitive` parameter requires a payment token with scope `payments:validate` or `payments:allow-sensitive`. ## List a payment connector incompatibilities `GET` `https://{domain}.biapi.pro/2.0/payments/{paymentId}/incompatibilities` #### Query Parameters

Name	Type	Required	Description
all	Boolean	No	Set to true to return incompatibilities for all connectors, including hidden ones.

{% tabs %} {% tab title="200: OK List of payment connector compatibilities" %} Response body: Array of [#paymentconnectorincompatibility-resource](#paymentconnectorincompatibility-resource "mention") {% endtab %} {% endtabs %} ## Webhooks ### Payment state updated A `PAYMENT_STATE_UPDATED` webhook is emitted after a payment state has been updated. Webhook request body: [#payment-resource](#payment-resource "mention") The `PAYMENT_STATE_UPDATED` event data will be triggered for every payment state change. {% hint style="warning" %} If your domain was created before 2024/09/13, the old behaviour of the webhook is used instead. The `PAYMENT_STATE_UPDATED` event data will only be sent when the payment state is updated in a non-interactive operation. This corresponds to two scenarios: * The payment request has been validated by the PSU, and during a regular background check on the payment with the bank, we have detected a change in its state. * The payment request has been validated by the PSU, but they have not been redirected to our callback (network issues, browser closed too early, crash, anomalous behavior of the bank's interface, ...). This case falls back to background checks, as described above. Please note that if the validation flow succeeds and the new state is communicated in your callback, the webhook will not be triggered until a later update. To switch to the new behaviour of the webhook, please set the configuration key `payment.state_updated_webhook.systematic` to `'1'`, or contact the support team. {% endhint %} ## Request payloads ### *PaymentInitRequest* object {% hint style="info" %} This model is presented with two-step payment validation in mind, where the initial request is done by your client implementation and the validate request is done by the webview, as described [in the payment webview implementation guide](https://docs.powens.com/documentation/integration-guides/pay/advanced/implementing-your-own-payment-validation-webview#send-the-validation-request). {% endhint %}

Property	Type	Presence	Description
~~`id_connector`~~	Integer	Optional	(Deprecated) ID of the bank connector to pre-select for the payment. This property is deprecated in favor of `connector_uuid`.
`connector_uuid`	String	Optional	UUID of the bank connector to pre-select for the payment. The bank connector must be eligible to payments creation.
`client_redirect_uri`	String	Required	The redirect URL to use when building the validation URL. The provided URL must not contain any query parameter, rely on the `client_state` parameter for state management.
`client_state`	String	Optional	Optional value that will be added as a `state` query parameter to the redirect URL after validation. If provided, must be 2000 characters or less.
`instructions`	Array of PaymentInstruction	Required	The payment information.
`operator_identity`	Identity object	Optional	Detailed identity information about the entity initiating the payment.
`payer`	PaymentAccount object	Optional	Account information about the payer. This should be provided here in case the information is known beforehand; otherwise, the webview is responsible for requiring it from the end user if necessary.
`payer_identity`	Identity object	Optional	Detailed identity information about the payer/debtor.

### ***PaymentValidateRequest***** object** {% hint style="warning" %} This section is only useful if you're implementing your own webview; see [the corresponding guide](https://docs.powens.com/documentation/integration-guides/pay/advanced/implementing-your-own-payment-validation-webview) for more details. {% endhint %}

Property	Type	Presence	Description
~~`id_connector`~~	Integer	Optional	(Deprecated) ID of the bank connector to use to initiate the payment. This property is deprecated in favor of `connector_uuid`.
`connector_uuid`	UUID	Conditional	UUID of the bank connector to use to initiate the payment. Note that it may have been pre-selected at payment creation; see Select a connector for the payment for more information. The bank connector must be eligible to payments creation.
`validate` `_mechanism`	String	Required	Name of the mechanism to use to validate the payment. Compatibility note: this is set to `webauth` when not provided for now.
`fields`	String dictionary	Conditional	Encrypted static fields to provide for the payment. See end-to-end encryption for more details on how to encrypt.
~~`website`~~	String	Conditional	(Deprecated) Value to provide for the payment's `website` field, if such a field is required by the connector for payments. This property is deprecated in favor of `fields`, which can be used to communicate more fields than just `website`.
`payer`	PaymentAccount object	Conditional	Account information about the payer. This data is required for connectors that need the payer account, if no payer account data has been provided at payment creation.
`webview_url`	String	Required	URL to which to redirect the end user after `redirect` actions, for the validation process.
`validated`	Boolean	Optional	Provide `true` to acknowledge payment validation at once. Otherwise, validation is deferred.

### ***PaymentResumeRequest***** object** {% hint style="warning" %} This section is only useful if you're implementing your own webview; see [the corresponding guide](https://docs.powens.com/documentation/integration-guides/pay/advanced/implementing-your-own-payment-validation-webview) for more details. {% endhint %} This is the expected payload when the current action is `decoupled`.

Property	Type	Presence	Description
`resume`	Boolean	Required	Must be set to `true`.

### ***PaymentSubmitFieldValuesRequest***** object** {% hint style="warning" %} This section is only useful if you're implementing your own webview; see [the corresponding guide](https://docs.powens.com/documentation/integration-guides/pay/advanced/implementing-your-own-payment-validation-webview) for more details. {% endhint %} This is the expected payload when the current action is `additionalInformationNeeded`.

Property	Type	Presence	Description
`fields`	String dictionary	Required	Cleartext fields to provide for the payment.

### *PaymentSubmitPSUValidationRequest* object {% hint style="warning" %} This section is only useful if you're implementing your own webview; see [the corresponding guide](https://docs.powens.com/documentation/integration-guides/pay/advanced/implementing-your-own-payment-validation-webview) for more details. {% endhint %} This is the expected payload when the current action is `psuValidation`.

Property	Type	Presence	Description
`psu_validate`	Boolean	Required	Must be set to `true` if the PSU has validated the payment (or if PSU validation is considered implicit), or `false` otherwise.

### *PaymentConfirmRequest* object {% hint style="warning" %} This section is only useful if you're confirming payments manually. {% endhint %} This is the expected payload when the current action is `confirm`.

Property	Type	Presence	Description
`confirm`	Boolean	Required	Must be set to `true` if the payment should be confirmed, or `false` otherwise.

### ***PaymentCancelRequest***** object**

Property	Type	Presence	Description
`client_redirect` `_uri`	String	Required	The redirect URL to use when building the validation URL. The provided URL must not contain any query parameter, rely on the `client_state` parameter for state management.
`client_state`	String	Optional	Optional value that will be added as a `state` query parameter to the redirect URL after validation. If provided, must be 2000 characters or less.
`cancel`	Boolean	Required	Provide `true` to request payment cancellation.

### *PaymentTokenRequest* object

Property	Type	Presence	Description
`scope`	Scope string or array	Required	The `service` permissions to authorize for this token. The scope `payments:admin` cannot be granted to a restricted payment token.

## Responses ### *PaymentListResponse* object

Property	Type	Description
`payments`	Array of Payment objects	List of payments.

### *PaymentTokenResponse* object

Property	Type	Description
`token`	String	The generated service token.
`scope`	String	The attributed permissions for this service token.
`id_payment`	Integer	The payment ID linked to the token.

## Code sets ### *IdentityKind* values

Value	Description
`individual`	Individual (personne physique).
`corporate`	Corporate entity (entreprise).
`non_profit`	Non-profit (association).
`government`	Government agency (agence gouvernementale).

### ***IdentitySchemeName***** values**

Value	Relevant identity kind	Description
`national_id_number`	individual	National identification number.
`passport_number`	individual	Passport number.
`alien_reg_number`	individual	Alien registration number.
`siren`	corporate, non_profit	French SIREN company identification number.
`incorporation_number`	corporate, non_profit, government	Incorporation number.
`euid`	corporate, non_profit	European Unique Identifier.
`rna`	non_profit	French RNA non profit organization identification number.

### ***PaymentAccountSchemeName***** values**

Value	Description
`iban`	International Bank Account Number.
`sort_code_account_number`	United Kingdom local account number.

### ***ExecutionDate***** values**

Value	Description
`first_open_day`	The payment is executed on the first business day of the bank. For most banks, this excludes the current day.
`deferred`	The payment will be executed on the given execution date.
`instant`	The payment will be executed in a short time delay, depending on the payer and beneficiary banks. For most banks, the payment status is final after the payment confirmation.
`periodic`	The payment is executed periodically at the given frequency.

{% hint style="warning" %} The `periodic` date type is not available by default. Please check with your commercial contact to enable this feature. {% endhint %} ### ***ExecutionFrequency***** values**

Value	Description
`daily`	Every day. Note that most banks do not support this frequency.
`weekly`	Every week.
`two-weekly`	Every two weeks.
`monthly`	Every month.
`two-monthly`	Every two months.
`quarterly`	Every three months.
`four-monthly`	Every four months.
`semiannually`	Every six months.
`yearly`	Every year.

### ***PaymentState***** values**

Value	Kind	Description
`created`	Intermediate state	The payment request was registered, but not yet validated.
`validating`	Intermediate state	The payment request was validated and initialized with the bank. The `validate_uri` is available.
`pending`	Intermediate state	The payment request has been validated on the bank website, but execution has not been confirmed yet.
`rejected`	Final state	The payment request has been rejected by the bank or the user. The `error_code` is available.
`done`	Final state	The payment has been executed and confirmed by the bank.
`accepted`	Final state	The payment has passed acceptance checks from the banks and is awaiting execution. However the bank will not give us further update on the payment state.
`expired`	Final state	The payment has automatically expired because it did not have a definitive status (ie done or rejected) N days after its execution. N value is configurable with the `payment.manual_expire_time_days` configuration key.
`partial`	Final state	(Only for bulk payments) At least one instruction was rejected, and at least one instruction was either done or accepted.

The full state diagram is the following: {% @mermaid/diagram content="graph TB classDef positiveFinal fill:#2c88d9,color:white classDef negativeFinal fill:#f7c325,color:white classDef partialFinal fill:#ff7f00,color:white created("Created") validating("Validating") pending("Pending") done("Done") accepted("Accepted") partial("Partial") created -->|"Payment validated by end user"| validating validating -->|"Payment validated on the bank app/website"| pending pending -->|"Payment executed and
confirmed by the bank"| done pending -->|"First controls succeeded
but the bank will not
return more info"| accepted pending -->|"Bulk payment
with mixed accepted/done
and rejected instructions" | partial direction LR created -->|"No definitive status after X days"| expired\_after\_created("Expired") created -->|"Payment cancelled by client/PSU
or an error has occurred"| rejected\_after\_created("Rejected") validating -->|"No definitive status after X days"| expired\_after\_validating("Expired") validating -->|"Payment refused by bank or end user"| rejected\_after\_validating("Rejected") pending -->|"No definitive status after X days"| expired\_after\_pending("Expired") pending -->|"Rejected by bank or
cancelled by end user"| rejected\_after\_pending("Rejected") class done,accepted positiveFinal class partial partialFinal class expired\_after\_created,rejected\_after\_created,expired\_after\_validating,rejected\_after\_validating,expired\_after\_pending,rejected\_after\_pending negativeFinal" %} {% hint style="success" %} Payment in a final state will not change of state anymore, this is considered as an ending of the payment flow. {% endhint %} {% hint style="info" %} Forward compatibility requirement: additional states may be added in the future. When implementing state handling, always fallback to a non-resolvable generic case for unknown values. {% endhint %} ### *PaymentStateDetail* values

Value	Description
(null)	No state detail.
`cancelling`	The payment is currently being cancelled, and a user action is provided in the `action` field .

### ***PaymentAction***** values**

Value	Description
`redirect`	The end user must complete a redirect flow, for which the URL is present in `validate_uri`.
`decoupled`	A validation is required from the end user on a side channel, e.g. a mobile app or on a link sent in an email or an SMS.
`additionalInformation` `Needed`	Values for one or more fields are required from the end user. Such fields are provided in `fields`.
`confirm`	A confirmation is required from the client.
`psuValidation`	A validation is required from the end user.

### ***PaymentErrorCode***** values**

Value	Description
`invalidEmitter`	Identification of the emitter account is invalid, or transfer emission is not possible.
`insufficientFunds`	The balance of the emitter account is too low.
`invalidAmount`	The amount of the payment request is invalid or out of the authorized bounds.
`invalidCurrency`	The currency of the payment request is invalid or unsupported.
`invalidDate`	The execution date of the payment request is invalid or out of the supported bounds.
`invalidBeneficiary`	The beneficiary identification is invalid or unsupported.
`invalidLabel`	The label of the payment request does not match the constraints enforced by the bank.
`invalidReferenceId`	The reference ID of the payment request is not accepted by the bank.
`regulatoryReason`	The request was aborted by the bank for regulatory reason (e.g. fraud detection).
`authenticationFailed`	The request was aborted because the end-user failed to identify with the bank.
`noAnswerFromCustomer`	The payment request expired without any interaction with the end-user.
`noSpecifiedReason`	The payment request was rejected by the bank without any reason.
`CancelledByUser`	The payment was explicitly cancelled by the end-user.
`CancelledByClient`	The payment has been cancelled through the API.
`confirmationRefused`	The payment confirmation was refused by the client.
`bankMessage`	The bank sent an error message to the user.
`invalidValue`	The request contains invalid data.
`websiteUnavailable`	The connector is currently unavailable, typically happens if the bank's interface is unreachable.
`bug`	A bug has occurred during the request validation.

{% hint style="info" %} Forward compatibility requirement: additional codes may be added in the future. When implementing error handling, always fallback to a generic case for unknown values. {% endhint %} ### *PaymentInstructionState* values

Value	Kind	Description
`pending`	Intermediate state	The instruction's execution has not been confirmed yet.
`rejected`	Final state	The instruction has been rejected by the bank or the user. The `error_code` is available.
`done`	Final state	The instruction has been executed and confirmed by the bank.
`accepted`	Final state	The instruction has passed acceptance checks from the banks and is awaiting execution. However the bank will not give us further update on the payment state.

### ***PaymentFieldType***** values**

Value	Description
`text`	The field should be displayed as a simple text box.
`list`	The field should be displayed as a selection widget.

### ***PaymentConnectorIncompatibilityType***** values** | Value | Description | | -------------- | ------------------------------------------------------------------------------------- | | `incompatible` | The connector is incompatible with the payment. | | `warning` | The connector is compatible but some of the payment properties may cause a rejection. | ### ***PaymentConnectorIncompatibilityCode***** values**

Value	Description
`maxAmount`	The payment amount is above the known global transfer limit for this connector for this payment type. The PSU may still be able to unlock this limit with their bank.
`minAmount`	The payment amount is below the minimum amount required by this connector for this payment type.
`maxBulk`	The number of instructions for this bulk payment is above the maximum number of instructions allowed by the connector.
`maxDateDelta`	The payment execution date is too far for the connector.
`minDateDelta`	The payment execution date is not far enough for the connector.
`nspDateType`	The payment type is not supported by the connector.
`nspFrequency`	The periodic payment frequency is not supported by the connector.
`nspBulk`	This connector does not support bulk payments.
`nspBenefScheme`	The payment beneficiary identification scheme is not supported by the connector.
`nspPayer`	The connector does not allow providing a payer account.
`nspExecDate`	The payment execution date is not allowed by the connector.
`nspCurrency`	The payment currency is not supported by the connector.
`trustBenef`	The beneficiary needs to be trusted by the payer account.

## **Data structures** ### ***PaymentFieldValue***** object**

Property	Type	Description
`label`	String	Human-readable description of the choice.
`value`	String	Technical value to pass to select the value.

### ***PaymentField***** object**

Property	Type	Description
`name`	String	Technical name of the field, for the client to use to identify the corresponding value.
`type`	PaymentFieldType string	Type of field, to use to display the correct input widget to the end user.
`label`	String	Human-readable description of the field.
`regex`	String or null	Optional PCRE-compatible pattern for `text` fields.
`required`	Boolean	Whether the field is required or not.
`values`	Array of PaymentFieldValue objects	Values to choose from for `list` fields.

## **Resources** ### ***PaymentAccount***** resource**

Property	Type	Presence	Description
`scheme_name`	PaymentAccountSchemeName string	Required	The payment account number type.
`identification`	String	Required	The payment account number, of type matching the given `scheme_name`.
`label`	String	Required	Display name of the payment account.
`issuer`	String	Optional	The BIC of the payment account (when the `scheme_name` is `iban`).

{% hint style="warning" %} `merchant_scheme_name` and `merchant_identification` have been replaced by the use of `payer_identity` and `beneficiary_identity`. {% endhint %} ### ***Identity***** resource**

Property	Type	Options	Description
`id_user`	Integer		ID of the user related to this payment. If provided, this must be an existing User.
`kind`	IdentityKind string		The kind of entity the identity is linked to. If not provided, this property is set to `individual`.
`external_ref`	String		External reference assigned by the customer to the entity defined by this Identity. Maximum 255 characters.
`first_name`	String	Sensitive	First name. Maximum 255 characters.
`last_name`	String	Sensitive	Last name. Maximum 255 characters.
`birth_city`	String	Sensitive	City of birth.
`birth_country`	String	Sensitive	Country of birth, as an ISO 3166-1 alpha-2 code.
`birth_date`	Date	Sensitive	Date of birth.
`nationality`	String	Sensitive	Nationality.
`postal_address`	String	Sensitive	Postal address. Maximum 512 characters.
`email`	String	Sensitive	Email address. Maximum 255 characters.
`scheme_name`	IdentitySchemeName string	Sensitive	Identification number type. Required if `identification` is provided.
`identification`	String	Sensitive	Identification number. Maximum 255 characters.
`issuer`	String	Sensitive	Issuer of the identification. Maximum 255 characters.
`ultimate_owner` `_text`	String	Sensitive	Identity text of the first ultimate owner of the entity.
`ultimate_owner` `_extra_text`	String	Sensitive	Identity text for additional ultimate owners of the entity.
`pep`	Boolean	Sensitive	Is the person politically exposed. Defaults to `false`. Maximum 255 characters.
`org_name`	String		Entity name of the organization, required if `kind` is not `individual`. Maximum 255 characters.
`org_legal_status`	String		Legal status of the organization, required if `kind` is not `individual`. Maximum 128 characters.
`org_hq_address`	String	Sensitive	Headquarters address of the organization, required if `kind` is not `individual`. Maximum 512 characters.
`org_business_address`	String	Sensitive	Business address of the organization, required if `kind` is not `individual`. Maximum 512 characters.

Fields marked sensitive are only returned by the API if the `show_sensitive` query parameter is used. Required properties are the following:

Property	Individual	Corporate	Non-profit	Government
`kind`	N/A	Mandatory	Mandatory	Mandatory
`first_name`	Mandatory	N/A	N/A	N/A
`last_name`	Mandatory	N/A	N/A	N/A
`birth_city`	Recommended	N/A	N/A	N/A
`birth_country`	Recommended	N/A	N/A	N/A
`birth_date`	Recommended	N/A	N/A	N/A
`org_name`	N/A	Recommended	Recommended	Recommended
`scheme_name`	N/A	Mandatory	Mandatory	Mandatory
`identification`	N/A	Mandatory	Mandatory	Mandatory

Examples identities are the following: {% tabs %} {% tab title="Individual" %} ```json { "kind": "individual", "first_name": "Jean", "last_name": "Dupont", "birth_city": "Paris", "birth_country": "FR", "birth_date": "1990-12-31" } ``` {% endtab %} {% tab title="Individual without birth data" %} ```json { "kind": "individual", "first_name": "Jean", "last_name": "Dupont", "nationality": "FR", "postal_address": "Appartement 25\nEntrée B Résidence Les Iris\n3 Boulevard du Levant\n95220 HERBLAY", "external_ref": "MY-CUSTOMER-REFERENCE-012345678" } ``` {% endtab %} {% tab title="Company" %} ```json { "kind": "corporate", "org_name": "Powens", "org_legal_status": "SAS", "org_hq_address": "84 RUE BEAUBOURG\n75003 PARIS 3\nFRANCE", "scheme_name": "siren", "identification": "749867206" } ``` {% endtab %} {% tab title="Non-profit" %} ```json { "kind": "non_profit", "org_name": "Scouts et Guides de France", "org_legal_status": "Association loi du 1er juillet 1901", "org_hq_address": "21-37-BAT D 2E ETAGE, 21 RUE DE STALINGRAD, 94110 ARCUEIL", "scheme_name": "rna", "identification": "W751001142" } ``` {% endtab %} {% endtabs %} ### ***PaymentInstruction***** resource** {% hint style="info" %} End-to-end identifiers (represented by the `reference_id` property) vary in length depending on the payment instrument used: * SEPA Credit Transfers use 31 characters long end-to-end identifiers. * Domestic UK payments using Faster Payments use 18 characters long end-to-end identifiers. It is recommended **not** to provide end-to-end identifiers, so that the API can generate such of correct lengths depending on the situation.

Example

See an example when creating a bulk payment with 2 instructions without providing the `reference_id`: {% code title="Request" %} ```json POST /payments { "client_redirect_uri": "http://example.org", "instructions": [ { "label": "Payment test", "amount": "1", "currency": "EUR", "execution_date_type": "first_open_day", "beneficiary": { "scheme_name": "iban", "identification": "FR4630003000704114151355Z51", "label": "Fake IBAN" } }, { "label": "Payment test 2", "amount": "1", "currency": "EUR", "execution_date_type": "first_open_day", "beneficiary": { "scheme_name": "iban", "identification": "FR1420041010050500013M02606", "label": "Fake IBAN" } } ] } ``` {% endcode %} {% code title="Response" %} ```json { "id": 1975, "state": "created", "error_code": null, "error_description": null, "register_date": "2022-09-29 08:05:30", "validate_uri": null, "client_redirect_uri": "http://example.org", "state_detail": null, "id_connector": null, "instructions": [ { "reference_id": "10mrPLcJVSlf7YFnX6MsfmRfnQT-1", "execution_date_type": "first_open_day", "label": "Payment test", "amount": 1.0000000000, "currency": { "id": "EUR", "symbol": "€", "prefix": false, "crypto": false, "precision": 2, "marketcap": null, "datetime": null, "name": "Euro" }, "exec_date": null, "execution_date": null, "beneficiary": { "id": 6313, "id_account": null, "label": "Fake IBAN", "scheme_name": "iban", "identification": "FR4630003000704114151355Z51", "issuer": "SOGEFRPPXXX", "disabled_date": null, "merchant_scheme_name": null, "merchant_identification": null, "bic": "SOGEFRPPXXX" } }, { "reference_id": "10mrPLcJVSlf7YFnX6MsfmRfnQT-2", "execution_date_type": "first_open_day", "label": "Payment test 2", "amount": 1.0000000000, "currency": { "id": "EUR", "symbol": "€", "prefix": false, "crypto": false, "precision": 2, "marketcap": null, "datetime": null, "name": "Euro" }, "exec_date": null, "execution_date": null, "beneficiary": { "id": 6314, "id_account": null, "label": "Fake IBAN", "scheme_name": "iban", "identification": "FR1420041010050500013M02606", "issuer": "SOGEFRPPXXX", "disabled_date": null, "merchant_scheme_name": null, "merchant_identification": null, "bic": "SOGEFRPPXXX" } } ] } ``` {% endcode %}

{% endhint %}

Property	Type	Presence	Description
`reference_id`	String	Optional	The optional end-to-end identifier for the instruction. If not provided, a random identifier is generated (maximum 31 characters).
`amount`	Number	Required	The amount of the payment.
`currency`	String	Required	The currency code of the payment amount, a per ISO 4217.
`label`	String	Required	Label of the payment.
`execution_date_type`	ExecutionDate string	Required	The execution date type of the payment.
`execution_date`	Date	Conditional	The execution date for the transfer, only for `deferred` transfers. Must be a UTC date.
`beneficiary`	PaymentAccount object	Required	The beneficiary information for the payment instruction.
`beneficiary_identity`	Identity object	Optional	Detailed identity information about the beneficiary.
`start_date`	Date	Conditional	The starting date for `periodic` transfers. Required if `execution_date_type` is `periodic`.
`end_date`	Date	Optional	The ending date for `periodic` transfers. If none is provided, the transfer will be executed indefinitely until stopped manually.
`frequency`	Execution Frequency string	Conditional	The frequency of execution for `periodic` transfers. Required if `execution_date_type` is `periodic`.
`state`	PaymentInstructionState string or null	Computed	The current state of the instruction.

### ***Payment***** resource**

Property	Type	Description
`id`	Integer	The ID of the created payment request.
`state`	PaymentState string	The state of the payment request.
`state_detail`	PaymentStateDetail value	The state detail of the payment request.
`action`	PaymentAction string or null	The current action taking place on the payment request.
`error_code`	PaymentErrorCode string or null	The error code of the payment request.
`error` `_description`	String or null	Error message in case of an error.
`fields`	Dictionary of PaymentField objects	Fields to provide to the payment for `additionalInformationNeeded` actions.
`validate_uri`	String or null	URL to which to redirect the end user for `redirect` actions.
`id_connector`	Integer or null	(Deprecated) ID of the bank connector to use to initiate the payment. This property is deprecated in favor of `connector_uuid`.
`connector_uuid`	UUID or null	UUID of the bank connector to use to initiate the payment.
`validate` `_mechanism`	String or null	The chosen validation mechanism for the payment.
`register_date`	DateTime	Creation date of the payment request.
~~`client_redirect_uri`~~	String or null	(Deprecated) The final callback URL to redirect the end user to at the end of the payment validation process. Prefer using the `redirect_uri` parameter to the payment validation webview instead.
~~`client_state`~~	String or null	(Deprecated) The optional state to add to the final callback URL. Prefer using the `state` parameter to the payment validation webview instead.
`payer`	PaymentAccount object	The payer information for the payment.
`instructions`	Array of PaymentInstruction objects	The list of payment instructions.
`payer_identity`	Identity object	Detailed identity information about the payer/debtor.

### ***PaymentConnectorIncompatibility***** resource**

Property	Type	Description
`type`	PaymentConnectorIncompatibilityType string	Whether the payment is incompatible with the connector, or if it's simply a warning.
`reasons`	Array of PaymentConnectorIncompatibilityReason objects	The exhaustive list of reasons causing warnings or incompatibilities.

### ***PaymentConnectorIncompatibilityReason***** resource**

Property	Type	Description
`code`	PaymentConnectorIncompatibilityCode string	The compatibility code. Indicates the nature of the incompatibility or warning.
`type`	PaymentConnectorIncompatibilityType string	Whether the reason caused a warning or incompatibility.
`description`	string	Technical description of the incompatibility code.
`value_connector`	String or Decimal or Bool or Array or Object	For parametrized incompatibility rules, this is the value associated to the connector to put in comparison with the value exposed in `value_payment`.
`value_payment`	String or Decimal or Bool or Array or Object	For parametrized incompatibility rules, this is the value associated to the payment to put in comparison with the value exposed in `value_connector`.