Operations

Operations stand for banking operations originating from or targeting a Wallet (i.e., Card Transactions, Payins, Payouts, and Transfers) and their refunds. Each Operation summarizes the initial transaction with read-only information such as the nature, status, amount, origin, and destination.

Therefore, you may use Operations as a single source of information. They are what end users generally expect to see as a table or timeline when they log into their bank website/app.

Tip – Operations are available in CSV format

You can also export the information using the Reports feature.

Available operations (`operationType`)

The operationType attribute allows you to identify what kind of banking operation is concerned.

The following operation types are available:

`operationType`	Initial operation
`bankDirectDebit`	SEPA Direct Debit (SDD)
`bankTransfer`	SEPA Transfer
`cardTopup`	Incoming funds from Card
`cardTransaction`	Outgoing Card payment
`check`	Check
`creditNote`	Wallet-to-wallet Transfers with a `transferTypeId` value of `4`. Such transfers allow you to handle reimbursement of charges.
`fees`	Wallet-to-wallet Transfers with a `transferTypeId` value of `3`. Such transfers allow you to debit fees from end users wallets. They are identified as such in Account Statements.
`instantBankTransfer`	Instant SEPA Transfer
`walletTransfer`	Wallet-to-wallet Transfers

Key attributes

Below are a few of the most important attributes.

Attribute	Type	Description
`operationType`	string	The type of bank operation, providing functional context about the initial operation.
`initialFlow`	string	Provides technical context about the initial operation: `payin`, `payinRefund`, `payout`, `payoutRefund`, `transfer`, `cardTransaction`, `chargeback`. You can fetch the initial operation by making the corresponding request (using the `objectId` as a path parameter).
`amount`	integer	The amount of the operation in cents (e.g., `100` stands for 1)
`walletId`	integer	The unique identifier of the wallet associated with the operation.
`direction`	string	Direction of the operation, which can either be: `CREDIT` – The funds are credited to the Wallet `DEBIT` – The funds are debited from the Wallet
`objectId`	string	The unique identifier of the object the operation relates to (e.g., the initial `cardTransaction`).
`label`	string	Information that you can expose to your end users. The label content differs depending on the context.
`metadata`	object	Details about the initial operation.
`status`	string	The status of the operation, which can be: `AUTHORIZED` `DECLINED` `SETTLED` `CANCELED`
`creation`	string	The date and time at which the object the operation relates to was created. Format: RFC3339 standard.
`settlement`	string	The date and time at which the object the operation relates to was settled on the Wallet. Format: RFC3339 standard.

API Reference – Refer to endpoint documentation

For a complete list of Operation attributes, check the Operations endpoint in the API Reference.

Metadata

The metadata object contains key information about the initial operation. This content differs depending on the operation.

Transfers

JSON

json

"metadata": {
  "label": "string || null",
  "codeStatus": "string",
  "tag": "string || null",
  "informationStatus": "string || null",
  "creditorWalletId": "string",
  "creditorFirstName": "string",    // Encrypted if cryptography is activated
  "creditorLastName": "string",     // Encrypted if cryptography is activated
  "creditorLegalName": "string",    // Encrypted if cryptography is activated
  "creditorWalletEventName": "string",
  "debtorWalletId": "string",       // Encrypted if cryptography is activated
  "debtorFirstName": "string",      // Encrypted if cryptography is activated
  "debtorLastName": "string",       // Encrypted if cryptography is activated
  "debtorLegalName": "string",
  "debtorWalletEventName": "string"
  }

Card Transactions

JSON

json

"metadata": {
  "maskedPan": "519872******4839",  // Encrypted if cryptography is activated
  "mcc": {
    "code": 123456,
    },
  "mid": {
    "value": "3256",          // MerchantId, Encrypted if cryptography is activated
    "name": "Merchant Name",  // MerchantName, Encrypted if cryptography is activated
    "city": "",               // MerchantCity, Encrypted if cryptography is activated
    "country": "",
    "address": null
  },
  "localAmount": {
    "amount": 1790,
    "currency": "978"
  },
  "authorizationNote": "",  // Encrypted if cryptography is activated
  "authorisationResponseCode": {
    "action": "Approved",
    "description": "APPROVED",
    "value": 08
  },
  "paymentLifeCycle": [     // for each Cardtransactions::PaymentStatus = S
    {
      "authorizationIssuerTime": "2024-04-16 08:23:20",
      "valueDate": "string",
      "paymentAmount": 0,  
      "paymentLocalAmount": 0,
      "paymentCurrency": "string"
    }
  ],
  "paymentCountry": "FRA",
  "cardId": "999997173", 
  "publicToken": "string",
  "is3DS":"0",
  "3dsExemptionType":"string || null", 
  "optimizedMerchantName":"string || null", 
  "merchantLogo":"string || null",
  "merchantCategory":"string || null", 
  "transactionSubtype":"string || null",
}

Payins

JSON

json

"metadata": {
  "payinId": "string",
  "payinTag": "string || null",       // Encrypted if cryptography is activated
  "messageToUser": "string || null",  // Encrypted if cryptography is activated
  "codeStatus": "string",
  "informationStatus": "string || null",
  "paymentMethodId": 0,
  "ibanFullName": "string || null",
  "dbtrIBAN": "******1319",           // Encrypted if cryptography is activated
  "ibanTxEndToEndId": "string || null",
  "mandateId": "string || null",
  "debtorName": "string || null",
  "uniqueMandateReference": "string || null",
  "additionalData": ["string"],       // Encrypted if cryptography is activated
}

PayinRefunds

JSON

json

"metadata": {
  "payinId": "string", 
  "payinTag": "string || null",       // Encrypted if cryptography is activated
  "messageToUser": "string || null",  // Encrypted if cryptography is activated
  "codeStatus": "string",
  "informationStatus": "string || null",
  "paymentMethodId": 0,
  "ibanFullName": "string || null",
  "dbtrIBAN": "string || null",       // Encrypted if cryptography is activated
  "ibanTxEndToEndId": "string || null",
  "mandateId": "string || null",
  "debtorName": "string || null", 
  "uniqueMandateReference": "string || null",
  "reasonTms":"string || null", 
  "additionalData": ["string"]        // Encrypted if cryptography is activated
}

Payouts

JSON

json

"metadata": {
  "payoutTag": "string || null", 
  "beneficiaryId": "string", 
  "label": "string || null",
  "codeStatus": "string",
  "informationStatus": "string || null",
  "payoutTypeId": 0, 
  "supportingFileLink": "string || null",
  "reasonCode": "string || null",
  "reasonDescription": "string || null",
  "endToEndId": "string || null",              // SCT only
  "uniqueMandateReference": "string || null",  // SDD only
  "beneficiaryName": "string || null"
}

PayoutRefunds

JSON

json

"metadata": {
  "codeStatus": "string",
  "informationStatus": "string || null",
  "requestComment": "string || null",
  "reasonCode": "string || null",
  "refundDate": "string || null",
  "refundComment": "string || null",
  "payoutId": "string || null",
  "payoutRefundTag": "string || null",
  "beneficiaryName": "string || null",
  "label": "string || null",
  "endToEndId": "string || null",             // SCT only
  "uniqueMandateReference": "string || null", // SDD only
  "payoutTypeId": 0,
  "beneficiaryId": "string || null",
  "payoutTag": "string"
}

Chargebacks

Chargebacks of card top up payins.

JSON

json

"metadata": {
  "payinId" : "string",
  "payinTag": "string || null",   // Encrypted if cryptography is activated
  "payinrefundId": "string",
  "additionalData": "string",     // Encrypted if cryptography is activated
  "chargebackReason": "string",
  "transactionReference":"string",
}

Labels

You can expose the label field values to your end users to provide more information.

The information displayed depends on the context and the table below relies on the latest version of the Operations feature.

Context	Exposed data	String example
Card Top Up	Indicates the name of the cardholder, along with the masked PAN of the card.	Alex Oak 553896XXXXXX8893
Cancelled Card Top Up	Indicates the name of the cardholder, along with the masked PAN of the card.	Alex Oak 553896XXXXXX8893
Chargeback on Card Top Up	Indicates the name of the cardholder and the card masked PAN.	Alex Oak 553896XXXXXX8893
Bank Transfer (Payin)	Indicates the IBAN full name, along with the `messageToUser` (custom field).	Alex Oak messageToUserExample
Refund of Bank Transfer (Payin)	Indicates the IBAN full name, along with the `messageToUser` (custom field).	Alex Oak messageToUserExample
Bank Transfer (Payout)	Indicates the Beneficiary name, along with the Payout `label`.
Refund of Bank Transfer (Payout)	Indicates the Beneficiary name, along with the Payout `label`.
Bank Direct Debit (Payin)	Indicates the debtor's name, along with the `messageToUser` (custom field), and the Unique Mandate Reference.
Refund of Bank Direct Debit (Payin)	Indicates the debtor's name, along with the `messageToUser` (custom field), and the Unique Mandate Reference.
Bank Direct Debit (Payout)	Indicates the Beneficiary name, the Payout `label`, and the Unique Mandate Reference.	Alex Oak rlabel96 UMR: 65c32b8dc64xx
Refund of Bank Direct Debit (Payout)	Indicates the Beneficiary name, the Payout `label`, and the Unique Mandate Reference.	Alex Oak rlabel96 UMR: 65c32b8dc64xx
Check	Indicates the user's name, along with the `messageToUser` (custom field), and the CMC7 A.
Refund of a Check	Indicates the user's name, along with the `messageToUser` (custom field), and the CMC7 A.
Transfer (wallet-to-wallet)	Indicates the user's name, along with the transfer `label`.	messageToUserExample Alex Oak
Transfer (if `fees` or `creditNote`)	Indicates the Transfer `label` (custom field).
Card Transaction	Indicates the merchant's name and the masked PAN. If the currency of the transaction differs from the Wallet currency, also indicates the `paymentLocalAmount`.	Tree Cie(978 91.78) Card 734837******9403

Retrieve operations

When requesting a list of operations, the following query parameters are required.

Parameter	Description
`walletId`	The unique identifier of the Wallet for which the operations are to be retrieved.
`dateFrom`	The date and time from which the operations are to be retrieved. This parameter takes into account the `createdDate` for Payin, Payout, and Transfer objects, and the `authorizationIssuerTime` for Card Transactions. Format: HTML-encoded RFC 339 date-time.
`dateTo`	The date and time up to which the operations are to be retrieved. This parameter takes into account the `createdDate` for Payin, Payout, and Transfer objects, and the `authorizationIssuerTime` for Card Transactions. Format: HTML-encoded RFC 339 date-time.

Note – 3-month time frame support

The dateTo and dateFrom fields must be less than 3 months apart.

To get the list of operations, use the following request (which supports cursor-based pagination). The dates are to be HTML encoded (e.g., 2024-01-11T11:25:36+01:00 becomes 2024-01-11T11:25:36%2B01:00).

CURL

bash

curl -X GET {baseUrl}/core-connect/operations?walletId={walletId}&dateFrom={dateFrom}&dateTo={dateTo} \
	--header 'Authorization: Bearer {accessToken}' \

Here is an example of a response. It returns an array of Operation objects along with a cursor and sorted by creation date.

JSON

json

{
    "cursor": {
        "prev": null,
        "current": null,
        "next": null
    },
    "data": [
        {
            "amount": {
                "amount": 1000,
                "currency": "EUR"
            },
            "walletId": 2647244,
            "operationType": "bankDirectDebit",
            "direction": "DEBIT",
            "status": "SETTLED",
            "objectId": "181212",
            "label": "Alex Oak rlabel96 UMR: 65c32b8dc64xx",
            "metadata": {
                "payoutTag": "65c32b8dc64xx|lFCS7WW4OugijXXX",
                "beneficiaryId": "429387",
                "beneficiaryName": "Alex Oak",
                "label": "rlabel96",
                "codeStatus": "160005",
                "informationStatus": "Remboursement par virement Validé",
                "payoutTypeId": 0, 
                "uniqueMandateReference": "65c32b8dc64xx",
                "supportingFileLink": "",
                "reasonCode": null,
                "reasonDescription": null,
                 "endToEndId": null   
            },
            "date": {
                "creation": "2024-02-07T08:04:48+01:00",
                "settlement": "2024-02-07T00:00:00+01:00"
            },
            "initialFlow": "payout"
        }
    ]
}

Generate Operation Reports

Operation Reports are CSV exports that include all operations for a given Wallet on a given period. They are mainly intended for administrative and back end use.

Creating an operation report is a 2-step process:

Request the Report
Retrieve the Report

Request a Report

To request a CSV report, you can use the following request.

CURL

bash

curl -X POST {baseUrl}/core-connect/operations/{walletId}/report \
    --header 'Authorization: Bearer {accessToken}' \
    --header 'Content-Type: application/json' \
    -d '{payload}'

Here is a {payload} example:

JSON

json

{
    "dateFrom":"2022-06-05T00:00:00+02:00",
    "dateTo":"2023-06-15T00:00:00+02:00"
}

Answers with a 201 HTTP Status code.

Retrieve a Report

To check on a report creation and obtain the download URL, you can use the following request.

Note – Parameters are expected in query string

As opposed to the POST request, the dateFrom and dateTo are expected as query parameters. The dates are to be html encoded (e.g., 2024-01-11T11:25:36+01:00 becomes 2024-01-11T11:25:36%2B01:00).

CURL

bash

curl -X GET {baseUrl}/core-connect/operations/{walletId}/report?dateFrom={dateFrom}&dateTo={dateTo} \
    --header 'Authorization: Bearer {accessToken}' \

Returns the following when the report is still being generated.

JSON

json

{ 
    "status": "CREATED", 
    "url": null 
}

Returns the following when the report is ready for download.

JSON

json

{ 
    "status": "COMPLETED", 
    "url": "https://dev-connect-files.s3.eu-west-3.amazonaws.com/operation/report/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx.csv"
}

Information – Report creation can time out

If 15 minutes after the initial Report request you are still getting the CREATED status, then the Report creation process has timed out.

Operation object

JSON

json

{
  "operationType": "bankTransfer",
  "initialFlow": "payout",
  "amount": {
    "amount": 6300, 
    "currency": "EUR", 
  },
  "walletId": 630632, 
  "direction": "DEBIT", 
  "objectId": "408265455", 
  "label": "Theo West Virement de M Alex Oak", 
  "metadata": {
      "payoutTag": "VO - 1234554321",
      "beneficiaryId": "404897",
      "label": "Virement de M Alex Oak",
      "codeStatus": "140005",
      "informationStatus": "",
      "supportingFileLink": "",
      "reasonCode": null,
      "reasonDescription": null,
      "beneficiaryName": "Yvy Sala"
  },
  "status": "AUTHORIZED", 
  "date": {
    "creation": "2023-08-19T06:08:23+02:00", 
    "settlement": null  
  }
}

Endpoints

Endpoint	Scope
`/core-connect/operations` Search Operations	`read_only`
`/core-connect/operations/{walletId}/report` Create a Report	`read_only`
`/core-connect/operations/{walletId}/report` Get a Report	`read_only`
`/simulation/operations` Simulate operations	`read_write`

Operations ​

Available operations (operationType) ​

Key attributes ​

Metadata ​

Transfers ​

Card Transactions ​

Payins ​

PayinRefunds ​

Payouts ​

PayoutRefunds ​

Chargebacks ​

Labels ​

Retrieve operations ​

Generate Operation Reports ​

Request a Report ​

Retrieve a Report ​

Operation object ​

Endpoints ​

Operations

Available operations (`operationType`)

Key attributes

Metadata

Transfers

Card Transactions

Payins

PayinRefunds

Payouts

PayoutRefunds

Chargebacks

Labels

Retrieve operations

Generate Operation Reports

Request a Report

Retrieve a Report

Operation object

Endpoints