PayIns, PayOuts and Transfers
Move money: PayIns to top up, PayOuts to debit, transfers between wallets.
Create PayIn
PayIn is Sovera API's method for adding funds to a specific wallet. It is a simple call that loads the information of the 'walletId' to which funds are to be loaded, the amount to be credited to the wallet in cents, the code of the currency according to ISO 4217, and a description of the transaction.
{
"walletIdTo": "string",
"amount": 0,
"currency": "string",
"statement": "string"
}{
"success": true,
"data": {
"id": "string",
"walletIdTo": "string",
"amount": 0,
"currency": "string",
"statement": "string",
"creationDate": "2022-07-20T20:47:04.060Z"
},
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}The successful response of this call, in addition to the provided information, includes a timestamp with the execution date of the transaction and a unique transaction identifier that allows retrieving the associated information with the GET call.
If there is a problem with the data provided the Sovera API will respond with an error envelope.
{
"success": false,
"errors": [
{ "code": "NOT_FOUND", "message": "Wallet not found" }
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}{
"success": false,
"errors": [
{ "code": "VALIDATION_ERROR", "message": "currency code does not match target walletId", "field": "currency" }
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}Retrieve PayIn
The GET call for a PayIn allows accessing information related to a specific transactionId. The successful response of this call loads the following structure:
https://api.sandbox.sovera.io/cards/v2/pay/ins/{PAYIN_ID}{
"success": true,
"data": [
{
"id": "string",
"walletIdTo": "string",
"amount": 0,
"currency": "string",
"statement": "string",
"creationDate": "2022-07-20T20:47:04.056Z"
}
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}On success, the API responds with HTTP 200 OK and returns the requested transaction.
The call may fail if an incorrect walletId is provided, in which case the Sovera API would respond with a HTTP 404 error.
Not found. An unknown transaction id returns HTTP 404:
{
"success": false,
"errors": [
{ "code": "NOT_FOUND", "message": "Transaction id '{id}' not found" }
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}Create PayOut
PayOut is a method to debit funds available in a specific wallet. Unlike a transfer, using this method eliminates the existence of the funds from the Sovera API. This method should be associated with an accounting operation that requires such a call.
Similar to PayIn, the successful response will return the entered data accompanied by a unique transaction identifier and its timestamp.
{
"walletIdFrom": "string",
"amount": 0,
"currency": "string",
"statement": "string"
}{
"success": true,
"data": {
"id": "string",
"walletIdFrom": "string",
"amount": 0,
"currency": "string",
"statement": "string",
"creationDate": "2022-07-20T20:47:04.060Z"
},
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}If there is a problem with the data provided the Sovera API will respond with an error envelope.
{
"success": false,
"errors": [
{ "code": "NOT_FOUND", "message": "Wallet not found" }
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}{
"success": false,
"errors": [
{ "code": "VALIDATION_ERROR", "message": "currency code does not match target walletId", "field": "currency" }
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}{
"success": false,
"errors": [
{ "code": "VALIDATION_ERROR", "message": "Wallet does not have sufficient funds" }
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}Retrieve PayOut
The GET call for a PayOut allows access to information related to a specific transactionId. The successful response of this call loads the following structure:
https://api.sandbox.sovera.io/cards/v2/pay/outs/{PAYOUT_ID}{
"success": true,
"data": [
{
"id": "string",
"walletIdTo": "string",
"amount": 0,
"currency": "string",
"statement": "string",
"creationDate": "2022-07-20T20:47:04.056Z"
}
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}On success, the API responds with HTTP 200 OK and returns the requested transaction.
The API will respond with an HTTP 404 error if it is an incorrect transactionId or a transactionId that is not related to a PayOut.
Create Transfer
To carry out transactions within the Sovera API environment between two previously created wallets, the Transfer POST call must be used, which has the following structure:
{
"walletIdFrom": "string",
"walletIdTo": "string",
"amount": 0,
"currency": "string",
"statement": "string"
}{
"success": true,
"data": {
"id": "string",
"walletIdFrom": "string",
"walletIdTo": "string",
"amount": 0,
"currency": "string",
"statement": "string",
"creationDate": "2022-07-22T15:54:08.059Z"
},
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}In this call, you must specify the walletIdFrom which the funds are being sent and the walletIdTo which the funds are being sent. The "currency" field must load the code of the currency associated with both wallets following the ISO 4217 standard.
The Sovera API does not manage currency conversions, so it is necessary to consider that both wallets must be configured under the same currency.
The amount entered in the "amount" field must be in cents following the standard of the other Sovera API calls.
The "statement" field allows you to enter a description of the transaction for future reference and display on the front-end.
The successful response to this call loads a unique transaction identifier and the timestamp of its acceptance.
In case of an error in the call, the Sovera API will respond with a descriptive HTTP 400 error.
Commonly, the call will fail if the walletIds involved in the transaction belong to an inactive userId, that is, maintaining its "isActive" attribute as "false".
Similarly, the call will always fail if the walletIdFrom does not maintain the adequate balance to cover the transaction or when the currency code of both wallets is not the same as the transfer POST call.
Retrieve Transfer
The GET call for a transfer between wallets allows access to information related to a specific transactionId and carries the following structure:
https://api.sandbox.sovera.io/cards/v2/transfers/{TRANSFER_ID}{
"success": true,
"data": [
{
"id": "string",
"walletIdFrom": "string",
"walletIdTo": "string",
"amount": 0,
"currency": "string",
"statement": "string",
"creationDate": "2022-07-22T16:07:33.092Z"
}
],
"meta": {
"timestamp": "2026-06-04T17:50:15.334Z",
"version": "v2",
"traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
}
}On success, the API responds with HTTP 200 OK and returns the requested transaction.
The API will respond with an HTTP 404 error if an incorrect transaction ID is provided or if the transaction ID is not related to a transfer.