Transfer funds to wallet recipient

POST /transfers

Introduction

A transfer is the movement of funds between two wallet accounts. Each transfer consists of two transactions.

TRANSFER_OUT - debit transaction for moving money from sender customer balance
TRANSFER_IN - credit transaction for moving money into the recipient customer's balance

There are three types of participants in a transfer:

Customer wallets - regular users onboarded on embedded wallets solution
Legal Entity wallets - wallets, that belong to legal entities.
Merchant wallets - wallets belonging to the merchant.

These types of participants are treated differently from a regulatory perspective but used the same way for performing transfers.

For performing a transfer you need the following parameters:

amount - the amount in minor units
currencyCode - must match the sending account currency
sender.customerId - wallet customer id of the sender
sender.accountId - wallet account id of the sender account
recipient.customerId - wallet customer id of the recipient
recipient.accountId - wallet customer id of the recipient

Optional parameters:

fee (optional) - (In Development) fee collected by the merchant for this transfer. The fee is always collected in sending account currency.

Currency conversion

The transfer currency must always match the sender account currency. By default, the recipient account also must be in the same currency.

Currency conversion is not explicitly enabled. For currency conversion during transfers, contact a Paysafe sales representative.

Customer-to-merchant transfer

Set recipient field to the Merchant customer id and account id. These are set up during merchant onboarding. Set sender field to the respective customer id and account id that you want to charge.

Merchant-to-customer transfer

Set sender field to the Merchant customer id and account id. These are setup during merchant onboarding. Set recipient field to the respective customer id and account id to whom you want transfer funds.

Customer-to-customer transfer

Set sender and recipient fields with the respective customer and account ids of the transfer participants.

Transfer Async behavior

The transfers are executed asynchronously.

the response will contain the submitted information, without the deviceInfo,risk, and customerIp properties
the response will not contain transactions, since they are not yet created
Merchant must wait for the webhook for this transaction to confirm the final status of the operation - successful or not.
Until the webhook is received, the Merchant can query the transfer using the Transactions endpoint, using merchantRefNum. While the transfer is still in the queue, an empty response will be returned.

Merchant Fee collection

(In Development)

A fee can be collected by the merchant for the transfer. The fee parameter is passed in minor units and is always collected in sending account currency.

Fees are collected in preconfigured merchant fee collection account in the corresponding fee currency.

Request

Header Parameters

Signature stringrequired

HMAC

application/json

Body

required

amount int64required

Transaction amount in minor units.

fee int64

Transaction fee in minor units.

currencyCode Currency (string)required

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

sender

object

required

Account specific view of the slip.

customerId string

Customer id of the account owner.

recipient

object

required

Account specific view of the slip.

customerId string

Customer id of the account owner.

merchantRefNum stringrequired

Possible values: <= 50 characters

Merchant reference number associated witht the transaction.

deviceInfo

object

required

Provides information about the device that the end-customer uses to access the service.

appType stringrequired

Possible values: [WEB_APP, MOBILE_APP, API]

threatMetrixSessionId stringrequired

Possible values: <= 100 characters

ThreatMetrics session id.

customerIp ipv4required

Customer IP Address.

risk

object

Additional information required for risk evaluation.

customerRiskRating numberrequired

isScaPerformed boolean

isCustomerIPTrusted boolean

isBeneficiaryTrusted boolean

authentication

object

3DS Authentication details

threeDResult string

Possible values: <= 1 characters

This indicates the outcome of the Authentication.

eci number

This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated.

cavv string

Possible values: <= 80 characters

This is the Cardholder Authentication Verification Value, indicating that the transaction is authenticated.

reason TransferReason (string)

Possible values: [INITIAL_BALANCE_MIGRATION, CRYPTO_BUY, CRYPTO_SELL, TRADING_PAIR, DEPOSIT, WITHDRAWAL, MERCHANT_FEE, REFUND, CANCELATION, BONUS, CURRENCY_EXCHANGE, PURCHASE, PAYOUT, PEER_TRANSFER, OTHER]

The actual purpose of the transfer.

INITIAL_BALANCE_MIGRATION - after customer onboarding, migrations of existing balances
CRYPTO_BUY - the customer is buying crypto or other assets
CRYPTO_SELL - the customer is selling crypto or other assets
TRADING_PAIR - the transfer represents a trading pair transaction between customers with wallets
DEPOSIT - crediting the customer's wallet via non-Paysafe deposit options
WITHDRAWAL - debiting the customer's wallet via non-Paysafe withdrawal options
MERCHANT_FEE - charging a merchant fee
REFUND - refunding the customer on a previous transaction
CANCELATION - cancelation of a previous transaction
BONUS - customer is granted a bonus
CURRENCY_EXCHANGE - converting one currency to another
PURCHASE - the customer is purchasing goods or services from a merchant
PAYOUT - the merchant is compensating a customer for goods or services
PEER_TRANSFER - money transfer between customers with wallets
OTHER - any reason not explicitly mentioned in the transfers

reasonDescription stringdeprecated

Possible values: <= 200 characters

fxQuote string

(In Development) FX Quote ID for the transfer in case currency conversion is required. If not passed and currency conversion is required the rate would be automatically assigned.

transferDetails

object

Represents the details of a transfer.

reason TransferReason (string)required

The actual purpose of the transfer.

INITIAL_BALANCE_MIGRATION - after customer onboarding, migrations of existing balances
CRYPTO_BUY - the customer is buying crypto or other assets
CRYPTO_SELL - the customer is selling crypto or other assets
TRADING_PAIR - the transfer represents a trading pair transaction between customers with wallets
DEPOSIT - crediting the customer's wallet via non-Paysafe deposit options
WITHDRAWAL - debiting the customer's wallet via non-Paysafe withdrawal options
MERCHANT_FEE - charging a merchant fee
REFUND - refunding the customer on a previous transaction
CANCELATION - cancelation of a previous transaction
BONUS - customer is granted a bonus
CURRENCY_EXCHANGE - converting one currency to another
PURCHASE - the customer is purchasing goods or services from a merchant
PAYOUT - the merchant is compensating a customer for goods or services
PEER_TRANSFER - money transfer between customers with wallets
OTHER - any reason not explicitly mentioned in the transfers

description string

Possible values: <= 200 characters

Human readable description for the transfer.

Responses

Accepted

application/json

Schema

amount int64required

Transaction amount in minor units.

fee int64

Transaction fee in minor units.

currencyCode Currency (string)required

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

sender

object

required

Account specific view of the slip.

accountId string

Account identifier.

customerId string

Customer id of the account owner.

slipId string

Slip identifier.

transactions

object[]

List of transactions associated with this account, that belong to the s.

Array [

id stringrequired

Transaction id

slipId stringrequired

Transaction slip Id.

customerId stringrequired

Wallet customer id.

accountId stringrequired

Account Id associated with this transaction.

type TransactionType (string)

Possible values: [DEPOSIT, WITHDRAWAL, PAYOUT, CHARGEBACK_REVERSAL, RETURNED_WITHDRAWAL, CHARGEBACK, MERCHANT_FEE, TRANSACTION_FEE, DAILY_TRANSACTIONS_FEE, TRANSFER_IN, TRANSFER_OUT, TRANSFER_RETURN, REFUND, CURRENCY_EXCHANGE, PAYSAFE_FEE, PREPAID_CARD, PREPAID_CARD_AUTHORIZATION, APPLICATION_FEE, SET_UP_FEE, MONTHLY_MAINTENANCE_FEE]

Represents the type of the transaction.

amount int64

Transaction amount in minor units.

currencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

fee int64deprecated

Transaction fee in minor units. Deprecated in favor of fees field.

fees

object[]

Customer fees attached to the transaction.

Array [

amount int64required

Default value: 0

Amount of the merchant payment, in mintor units. If currency is not specified, then the main transaction currency is used.

currency Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

paymentReason FeePaymentReason (string)required

Possible values: [MERCHANT_FEE, ATM_FEE, FX_FEE, PAYSAFE_FEE, OTHER_FEE, SENDER_FEE, RECIPIENT_FEE, DEPOSIT_FEE, WITHDRAWAL_FEE]

Default value: OTHER_FEE

Fee payment reason.

SENDER_FEE - Fee that will be applied to sender party of transfer collected into partner merchant wallet.
RECIPIENT_FEE - Fee that will be applied to recipient client of transfer collected into partner merchant wallet.
DEPOSIT_FEE - Fee charged for deposit transactions collected into partner merchant wallet.
WITHDRAWAL_FEE - Fee charged for withdrawal transactions collected into partner merchant wallet.
MERCHANT_FEE - Fee for the payment service collected into partner merchant wallet.
PAYSAFE_FEE - Fee collected by Paysafe for the provided payment service. Usually Paysafe Fee is not directly applied to customer transactions.
ATM_FEE - Fee for ATM service, when using prepaid cards.
FX_FEE - Fee applied, when payment requires currency exchange.
OTHER_FEE - It could be used for any additional, unspecified fees that may be applied to a transaction

]

creationTime date-time

Represents RFC 3339, section 5.6 date-time.

lastChangeDate date-time

Represents RFC 3339, section 5.6 date-time.

direction stringrequired

Possible values: [CREDIT, DEBIT]

Transaction direction.

instrumentId stringdeprecated

ID of the payment instrument. Deprecated in favour of instrumentDetails.instrumentId field.

instrumentType InstrumentType (string)deprecated

Possible values: [SEPA_BANK_ACCOUNT, UK_BANK_ACCOUNT, US_BANK_ACCOUNT, CCI_BANK_ACCOUNT, CARD]

Represents the type of the instrument.

| Value | Description| |---|---| | SEPA_BANK_ACCOUNT| SEPA Bank account | | UK_BANK_ACCOUNT | UK Bank account | | US_BANK_ACCOUNT | US Bank account | | CCI_BANK_ACCOUNT | CCI Bank account | | CARD | Card |

paymentType PaymentType (string)

Possible values: [CARD, BANK_TRANSFER, RAPID_TRANSFER, TRANSFER]

Type of instrument. Used as discriminator for different Payment types.

CARD
BANK_TRANSFER
RAPID_TRANSFER
TRANSFER

status TransactionStatus (string)required

Possible values: [PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, REFUNDED, DECLINED]

Represents the status of a transaction.

PENDING - Transaction is created and further action is required by the customer.
PROCESSING - Transaction is scheduled for processing by the payment provider.
COMPLETED - Transaction is completed. Note that some transactions might be completed from Embedded Wallet point of view, but not from customer point of view, since money movement might take some time outside of the Embedded Wallet network.
FAILED - Transaction is failed. Check STATUS_REASON property for details.
CANCELLED - Transaction have been cancelled
REFUNDED - Valid only for deposit transactions.
DECLINED - transaction is declined.

statusReason string

Possible values: <= 60 characters

Status reason for FAILED transactions. See TransactionStatusReason for available values.

merchantRefNum ExternalId (string)

Possible values: non-empty and <= 40 characters

Customer identifier used in Partner system.

balance int64

Balance of the account after the transaction in minor currency units.

recipientReference string

Additional reference information for the recipient passed by the sender of the transaction. This information is not valid or present for all transaction types.

fxAmount

object

(In Development)

Contains the amount in converted currency during currency conversion.

amount integer

Converted amount (in minor units).

rate number

Currency conversion rate.

currency Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

transferDetails

object

Represents the details of a transfer.

reason TransferReason (string)required

The actual purpose of the transfer.

INITIAL_BALANCE_MIGRATION - after customer onboarding, migrations of existing balances
CRYPTO_BUY - the customer is buying crypto or other assets
CRYPTO_SELL - the customer is selling crypto or other assets
TRADING_PAIR - the transfer represents a trading pair transaction between customers with wallets
DEPOSIT - crediting the customer's wallet via non-Paysafe deposit options
WITHDRAWAL - debiting the customer's wallet via non-Paysafe withdrawal options
MERCHANT_FEE - charging a merchant fee
REFUND - refunding the customer on a previous transaction
CANCELATION - cancelation of a previous transaction
BONUS - customer is granted a bonus
CURRENCY_EXCHANGE - converting one currency to another
PURCHASE - the customer is purchasing goods or services from a merchant
PAYOUT - the merchant is compensating a customer for goods or services
PEER_TRANSFER - money transfer between customers with wallets
OTHER - any reason not explicitly mentioned in the transfers

description string

Possible values: <= 200 characters

Human readable description for the transfer.

cardPaymentDetails

object

deprecated

Details about a payment with customer's card.

This class is deprecated because it is now part of 'PaymentInstrumentTransactionDetails' with new name 'PrepaidCardInstrumentTransactionDetails'.

cardId string

Prepaid card ID.

mobileWalletType string

Possible values: [GOOGLE_PAY, APPLE_PAY, SAMSUNG_PAY]

Mobile wallet type.

obfuscatedCardNumber string

Obfuscated card number.

merchantDetails

object

name string

Merchant name.

location

object

city string

Merchant location city.

state string

Merchant location state.

zip string

Merchant location zip.

mcc

object

id string

Merchant category id.

name string

Merchant category name.

paymentAmount int64

Amount paid with customer's card, in minor units.

paymentAmountCurrencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

peerDetails

object

Represents the details of a peer.

firstName string

Peer first name.

lastName string

Peer last name.

instrumentDetails

object

Represents details about a customer's payment instrument.

instrumentId string

Instrument ID.

instrumentType

string

Possible values: [CARD, PREPAID_CARD, SEPA_BANK_ACCOUNT, US_BANK_ACCOUNT, UK_BANK_ACCOUNT, CCI_BANK_ACCOUNT]

Represents the type of an instrument.

Value	Description
CARD	Card
PREPAID_CARD	Prepaid Card
SEPA_BANK_ACCOUNT	SEPA Bank account
US_BANK_ACCOUNT	US Bank account
UK_BANK_ACCOUNT	UK Bank account
CCI_BANK_ACCOUNT	CCI Bank account

pan string

Card PAN (Primary account number).

brand string

Card brand. Could be VISA, MASTERCARD, etc.

bankName string

Card bank name.

description string

Name to be associated with the card.

cardId string

Prepaid card ID.

mobileWalletType string

Possible values: [GOOGLE_PAY, APPLE_PAY, SAMSUNG_PAY]

Mobile wallet type.

obfuscatedCardNumber string

Obfuscated card number.

authorizationId string

The ID of the original card authorization, before settlement.

merchantDetails

object

name string

Merchant name.

location

object

city string

Merchant location city.

state string

Merchant location state.

zip string

Merchant location zip.

mcc

object

id string

Merchant category id.

name string

Merchant category name.

paymentAmount int64

Amount paid with customer's card, in minor units.

paymentAmountCurrencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

]

recipient

object

required

Account specific view of the slip.

accountId string

Account identifier.

customerId string

Customer id of the account owner.

slipId string

Slip identifier.

transactions

object[]

List of transactions associated with this account, that belong to the s.

Array [

id stringrequired

Transaction id

slipId stringrequired

Transaction slip Id.

customerId stringrequired

Wallet customer id.

accountId stringrequired

Account Id associated with this transaction.

type TransactionType (string)

Represents the type of the transaction.

amount int64

Transaction amount in minor units.

currencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

fee int64deprecated

Transaction fee in minor units. Deprecated in favor of fees field.

fees

object[]

Customer fees attached to the transaction.

Array [

amount int64required

Default value: 0

Amount of the merchant payment, in mintor units. If currency is not specified, then the main transaction currency is used.

currency Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

paymentReason FeePaymentReason (string)required

Possible values: [MERCHANT_FEE, ATM_FEE, FX_FEE, PAYSAFE_FEE, OTHER_FEE, SENDER_FEE, RECIPIENT_FEE, DEPOSIT_FEE, WITHDRAWAL_FEE]

Default value: OTHER_FEE

Fee payment reason.

SENDER_FEE - Fee that will be applied to sender party of transfer collected into partner merchant wallet.
RECIPIENT_FEE - Fee that will be applied to recipient client of transfer collected into partner merchant wallet.
DEPOSIT_FEE - Fee charged for deposit transactions collected into partner merchant wallet.
WITHDRAWAL_FEE - Fee charged for withdrawal transactions collected into partner merchant wallet.
MERCHANT_FEE - Fee for the payment service collected into partner merchant wallet.
PAYSAFE_FEE - Fee collected by Paysafe for the provided payment service. Usually Paysafe Fee is not directly applied to customer transactions.
ATM_FEE - Fee for ATM service, when using prepaid cards.
FX_FEE - Fee applied, when payment requires currency exchange.
OTHER_FEE - It could be used for any additional, unspecified fees that may be applied to a transaction

]

creationTime date-time

Represents RFC 3339, section 5.6 date-time.

lastChangeDate date-time

Represents RFC 3339, section 5.6 date-time.

direction stringrequired

Possible values: [CREDIT, DEBIT]

Transaction direction.

instrumentId stringdeprecated

ID of the payment instrument. Deprecated in favour of instrumentDetails.instrumentId field.

instrumentType InstrumentType (string)deprecated

Possible values: [SEPA_BANK_ACCOUNT, UK_BANK_ACCOUNT, US_BANK_ACCOUNT, CCI_BANK_ACCOUNT, CARD]

Represents the type of the instrument.

paymentType PaymentType (string)

Possible values: [CARD, BANK_TRANSFER, RAPID_TRANSFER, TRANSFER]

Type of instrument. Used as discriminator for different Payment types.

CARD
BANK_TRANSFER
RAPID_TRANSFER
TRANSFER

status TransactionStatus (string)required

Possible values: [PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, REFUNDED, DECLINED]

Represents the status of a transaction.

PENDING - Transaction is created and further action is required by the customer.
PROCESSING - Transaction is scheduled for processing by the payment provider.
COMPLETED - Transaction is completed. Note that some transactions might be completed from Embedded Wallet point of view, but not from customer point of view, since money movement might take some time outside of the Embedded Wallet network.
FAILED - Transaction is failed. Check STATUS_REASON property for details.
CANCELLED - Transaction have been cancelled
REFUNDED - Valid only for deposit transactions.
DECLINED - transaction is declined.

statusReason string

Possible values: <= 60 characters

Status reason for FAILED transactions. See TransactionStatusReason for available values.

merchantRefNum ExternalId (string)

Possible values: non-empty and <= 40 characters

Customer identifier used in Partner system.

balance int64

Balance of the account after the transaction in minor currency units.

recipientReference string

Additional reference information for the recipient passed by the sender of the transaction. This information is not valid or present for all transaction types.

fxAmount

object

(In Development)

Contains the amount in converted currency during currency conversion.

amount integer

Converted amount (in minor units).

rate number

Currency conversion rate.

currency Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

transferDetails

object

Represents the details of a transfer.

reason TransferReason (string)required

The actual purpose of the transfer.

INITIAL_BALANCE_MIGRATION - after customer onboarding, migrations of existing balances
CRYPTO_BUY - the customer is buying crypto or other assets
CRYPTO_SELL - the customer is selling crypto or other assets
TRADING_PAIR - the transfer represents a trading pair transaction between customers with wallets
DEPOSIT - crediting the customer's wallet via non-Paysafe deposit options
WITHDRAWAL - debiting the customer's wallet via non-Paysafe withdrawal options
MERCHANT_FEE - charging a merchant fee
REFUND - refunding the customer on a previous transaction
CANCELATION - cancelation of a previous transaction
BONUS - customer is granted a bonus
CURRENCY_EXCHANGE - converting one currency to another
PURCHASE - the customer is purchasing goods or services from a merchant
PAYOUT - the merchant is compensating a customer for goods or services
PEER_TRANSFER - money transfer between customers with wallets
OTHER - any reason not explicitly mentioned in the transfers

description string

Possible values: <= 200 characters

Human readable description for the transfer.

cardPaymentDetails

object

deprecated

Details about a payment with customer's card.

This class is deprecated because it is now part of 'PaymentInstrumentTransactionDetails' with new name 'PrepaidCardInstrumentTransactionDetails'.

cardId string

Prepaid card ID.

mobileWalletType string

Possible values: [GOOGLE_PAY, APPLE_PAY, SAMSUNG_PAY]

Mobile wallet type.

obfuscatedCardNumber string

Obfuscated card number.

merchantDetails

object

name string

Merchant name.

location

object

city string

Merchant location city.

state string

Merchant location state.

zip string

Merchant location zip.

mcc

object

id string

Merchant category id.

name string

Merchant category name.

paymentAmount int64

Amount paid with customer's card, in minor units.

paymentAmountCurrencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

peerDetails

object

Represents the details of a peer.

firstName string

Peer first name.

lastName string

Peer last name.

instrumentDetails

object

Represents details about a customer's payment instrument.

instrumentId string

Instrument ID.

instrumentType

string

Possible values: [CARD, PREPAID_CARD, SEPA_BANK_ACCOUNT, US_BANK_ACCOUNT, UK_BANK_ACCOUNT, CCI_BANK_ACCOUNT]

Represents the type of an instrument.

Value	Description
CARD	Card
PREPAID_CARD	Prepaid Card
SEPA_BANK_ACCOUNT	SEPA Bank account
US_BANK_ACCOUNT	US Bank account
UK_BANK_ACCOUNT	UK Bank account
CCI_BANK_ACCOUNT	CCI Bank account

pan string

Card PAN (Primary account number).

brand string

Card brand. Could be VISA, MASTERCARD, etc.

bankName string

Card bank name.

description string

Name to be associated with the card.

cardId string

Prepaid card ID.

mobileWalletType string

Possible values: [GOOGLE_PAY, APPLE_PAY, SAMSUNG_PAY]

Mobile wallet type.

obfuscatedCardNumber string

Obfuscated card number.

authorizationId string

The ID of the original card authorization, before settlement.

merchantDetails

object

name string

Merchant name.

location

object

city string

Merchant location city.

state string

Merchant location state.

zip string

Merchant location zip.

mcc

object

id string

Merchant category id.

name string

Merchant category name.

paymentAmount int64

Amount paid with customer's card, in minor units.

paymentAmountCurrencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

]

merchantRefNum stringrequired

Possible values: <= 50 characters

Merchant reference number associated witht the transaction.

reason TransferReason (string)

The actual purpose of the transfer.

INITIAL_BALANCE_MIGRATION - after customer onboarding, migrations of existing balances
CRYPTO_BUY - the customer is buying crypto or other assets
CRYPTO_SELL - the customer is selling crypto or other assets
TRADING_PAIR - the transfer represents a trading pair transaction between customers with wallets
DEPOSIT - crediting the customer's wallet via non-Paysafe deposit options
WITHDRAWAL - debiting the customer's wallet via non-Paysafe withdrawal options
MERCHANT_FEE - charging a merchant fee
REFUND - refunding the customer on a previous transaction
CANCELATION - cancelation of a previous transaction
BONUS - customer is granted a bonus
CURRENCY_EXCHANGE - converting one currency to another
PURCHASE - the customer is purchasing goods or services from a merchant
PAYOUT - the merchant is compensating a customer for goods or services
PEER_TRANSFER - money transfer between customers with wallets
OTHER - any reason not explicitly mentioned in the transfers

reasonDescription stringdeprecated

Possible values: <= 200 characters

fxQuote string

(In Development) FX Quote ID for the transfer in case currency conversion is required. If not passed and currency conversion is required the rate would be automatically assigned.

transferDetails

object

Represents the details of a transfer.

reason TransferReason (string)required

The actual purpose of the transfer.

INITIAL_BALANCE_MIGRATION - after customer onboarding, migrations of existing balances
CRYPTO_BUY - the customer is buying crypto or other assets
CRYPTO_SELL - the customer is selling crypto or other assets
TRADING_PAIR - the transfer represents a trading pair transaction between customers with wallets
DEPOSIT - crediting the customer's wallet via non-Paysafe deposit options
WITHDRAWAL - debiting the customer's wallet via non-Paysafe withdrawal options
MERCHANT_FEE - charging a merchant fee
REFUND - refunding the customer on a previous transaction
CANCELATION - cancelation of a previous transaction
BONUS - customer is granted a bonus
CURRENCY_EXCHANGE - converting one currency to another
PURCHASE - the customer is purchasing goods or services from a merchant
PAYOUT - the merchant is compensating a customer for goods or services
PEER_TRANSFER - money transfer between customers with wallets
OTHER - any reason not explicitly mentioned in the transfers

description string

Possible values: <= 200 characters

Human readable description for the transfer.

id string

Withdrawal id generated during creation.

slipId string

Transfer slip id.

merchant

object

Account specific view of the slip.

accountId string

Account identifier.

customerId string

Customer id of the account owner.

slipId string

Slip identifier.

transactions

object[]

List of transactions associated with this account, that belong to the s.

Array [

id stringrequired

Transaction id

slipId stringrequired

Transaction slip Id.

customerId stringrequired

Wallet customer id.

accountId stringrequired

Account Id associated with this transaction.

type TransactionType (string)

Represents the type of the transaction.

amount int64

Transaction amount in minor units.

currencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

fee int64deprecated

Transaction fee in minor units. Deprecated in favor of fees field.

fees

object[]

Customer fees attached to the transaction.

Array [

amount int64required

Default value: 0

Amount of the merchant payment, in mintor units. If currency is not specified, then the main transaction currency is used.

currency Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

paymentReason FeePaymentReason (string)required

Possible values: [MERCHANT_FEE, ATM_FEE, FX_FEE, PAYSAFE_FEE, OTHER_FEE, SENDER_FEE, RECIPIENT_FEE, DEPOSIT_FEE, WITHDRAWAL_FEE]

Default value: OTHER_FEE

Fee payment reason.

SENDER_FEE - Fee that will be applied to sender party of transfer collected into partner merchant wallet.
RECIPIENT_FEE - Fee that will be applied to recipient client of transfer collected into partner merchant wallet.
DEPOSIT_FEE - Fee charged for deposit transactions collected into partner merchant wallet.
WITHDRAWAL_FEE - Fee charged for withdrawal transactions collected into partner merchant wallet.
MERCHANT_FEE - Fee for the payment service collected into partner merchant wallet.
PAYSAFE_FEE - Fee collected by Paysafe for the provided payment service. Usually Paysafe Fee is not directly applied to customer transactions.
ATM_FEE - Fee for ATM service, when using prepaid cards.
FX_FEE - Fee applied, when payment requires currency exchange.
OTHER_FEE - It could be used for any additional, unspecified fees that may be applied to a transaction

]

creationTime date-time

Represents RFC 3339, section 5.6 date-time.

lastChangeDate date-time

Represents RFC 3339, section 5.6 date-time.

direction stringrequired

Possible values: [CREDIT, DEBIT]

Transaction direction.

instrumentId stringdeprecated

ID of the payment instrument. Deprecated in favour of instrumentDetails.instrumentId field.

instrumentType InstrumentType (string)deprecated

Possible values: [SEPA_BANK_ACCOUNT, UK_BANK_ACCOUNT, US_BANK_ACCOUNT, CCI_BANK_ACCOUNT, CARD]

Represents the type of the instrument.

paymentType PaymentType (string)

Possible values: [CARD, BANK_TRANSFER, RAPID_TRANSFER, TRANSFER]

Type of instrument. Used as discriminator for different Payment types.

CARD
BANK_TRANSFER
RAPID_TRANSFER
TRANSFER

status TransactionStatus (string)required

Possible values: [PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, REFUNDED, DECLINED]

Represents the status of a transaction.

PENDING - Transaction is created and further action is required by the customer.
PROCESSING - Transaction is scheduled for processing by the payment provider.
COMPLETED - Transaction is completed. Note that some transactions might be completed from Embedded Wallet point of view, but not from customer point of view, since money movement might take some time outside of the Embedded Wallet network.
FAILED - Transaction is failed. Check STATUS_REASON property for details.
CANCELLED - Transaction have been cancelled
REFUNDED - Valid only for deposit transactions.
DECLINED - transaction is declined.

statusReason string

Possible values: <= 60 characters

Status reason for FAILED transactions. See TransactionStatusReason for available values.

merchantRefNum ExternalId (string)

Possible values: non-empty and <= 40 characters

Customer identifier used in Partner system.

balance int64

Balance of the account after the transaction in minor currency units.

recipientReference string

Additional reference information for the recipient passed by the sender of the transaction. This information is not valid or present for all transaction types.

fxAmount

object

(In Development)

Contains the amount in converted currency during currency conversion.

amount integer

Converted amount (in minor units).

rate number

Currency conversion rate.

currency Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

transferDetails

object

Represents the details of a transfer.

reason TransferReason (string)required

The actual purpose of the transfer.

INITIAL_BALANCE_MIGRATION - after customer onboarding, migrations of existing balances
CRYPTO_BUY - the customer is buying crypto or other assets
CRYPTO_SELL - the customer is selling crypto or other assets
TRADING_PAIR - the transfer represents a trading pair transaction between customers with wallets
DEPOSIT - crediting the customer's wallet via non-Paysafe deposit options
WITHDRAWAL - debiting the customer's wallet via non-Paysafe withdrawal options
MERCHANT_FEE - charging a merchant fee
REFUND - refunding the customer on a previous transaction
CANCELATION - cancelation of a previous transaction
BONUS - customer is granted a bonus
CURRENCY_EXCHANGE - converting one currency to another
PURCHASE - the customer is purchasing goods or services from a merchant
PAYOUT - the merchant is compensating a customer for goods or services
PEER_TRANSFER - money transfer between customers with wallets
OTHER - any reason not explicitly mentioned in the transfers

description string

Possible values: <= 200 characters

Human readable description for the transfer.

cardPaymentDetails

object

deprecated

Details about a payment with customer's card.

This class is deprecated because it is now part of 'PaymentInstrumentTransactionDetails' with new name 'PrepaidCardInstrumentTransactionDetails'.

cardId string

Prepaid card ID.

mobileWalletType string

Possible values: [GOOGLE_PAY, APPLE_PAY, SAMSUNG_PAY]

Mobile wallet type.

obfuscatedCardNumber string

Obfuscated card number.

merchantDetails

object

name string

Merchant name.

location

object

city string

Merchant location city.

state string

Merchant location state.

zip string

Merchant location zip.

mcc

object

id string

Merchant category id.

name string

Merchant category name.

paymentAmount int64

Amount paid with customer's card, in minor units.

paymentAmountCurrencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

peerDetails

object

Represents the details of a peer.

firstName string

Peer first name.

lastName string

Peer last name.

instrumentDetails

object

Represents details about a customer's payment instrument.

instrumentId string

Instrument ID.

instrumentType

string

Possible values: [CARD, PREPAID_CARD, SEPA_BANK_ACCOUNT, US_BANK_ACCOUNT, UK_BANK_ACCOUNT, CCI_BANK_ACCOUNT]

Represents the type of an instrument.

Value	Description
CARD	Card
PREPAID_CARD	Prepaid Card
SEPA_BANK_ACCOUNT	SEPA Bank account
US_BANK_ACCOUNT	US Bank account
UK_BANK_ACCOUNT	UK Bank account
CCI_BANK_ACCOUNT	CCI Bank account

pan string

Card PAN (Primary account number).

brand string

Card brand. Could be VISA, MASTERCARD, etc.

bankName string

Card bank name.

description string

Name to be associated with the card.

cardId string

Prepaid card ID.

mobileWalletType string

Possible values: [GOOGLE_PAY, APPLE_PAY, SAMSUNG_PAY]

Mobile wallet type.

obfuscatedCardNumber string

Obfuscated card number.

authorizationId string

The ID of the original card authorization, before settlement.

merchantDetails

object

name string

Merchant name.

location

object

city string

Merchant location city.

state string

Merchant location state.

zip string

Merchant location zip.

mcc

object

id string

Merchant category id.

name string

Merchant category name.

paymentAmount int64

Amount paid with customer's card, in minor units.

paymentAmountCurrencyCode Currency (string)

Possible values: >= 3 characters and <= 3 characters

Currency alphabetic code as specified by ISO 4217

]

status TransactionStatus (string)

Possible values: [PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, REFUNDED, DECLINED]

Represents the status of a transaction.

PENDING - Transaction is created and further action is required by the customer.
PROCESSING - Transaction is scheduled for processing by the payment provider.
COMPLETED - Transaction is completed. Note that some transactions might be completed from Embedded Wallet point of view, but not from customer point of view, since money movement might take some time outside of the Embedded Wallet network.
FAILED - Transaction is failed. Check STATUS_REASON property for details.
CANCELLED - Transaction have been cancelled
REFUNDED - Valid only for deposit transactions.
DECLINED - transaction is declined.

{
  "amount": 1000,
  "fee": 100,
  "currencyCode": "EUR",
  "sender": {
    "accountId": "5014567344",
    "customerId": "5435323362",
    "slipId": "5009964049",
    "transactions": [
      {
        "id": "544232",
        "slipId": "5009964049",
        "customerId": "5435323362",
        "accountId": "212345",
        "type": "DEPOSIT",
        "amount": 1000,
        "currencyCode": "EUR",
        "fees": [
          {
            "amount": 1000,
            "currency": "EUR",
            "paymentReason": "OTHER_FEE"
          }
        ],
        "creationTime": "2021-07-15T17:54:12Z",
        "lastChangeDate": "2021-07-15T17:54:12Z",
        "direction": "CREDIT",
        "paymentType": "CARD",
        "status": "COMPLETED",
        "statusReason": "string",
        "merchantRefNum": "af5c8b52-0afd-4799-85ab-fe659a076932",
        "balance": 0,
        "recipientReference": "string",
        "fxAmount": {
          "amount": 0,
          "rate": 0,
          "currency": "EUR"
        },
        "transferDetails": {
          "reason": "INITIAL_BALANCE_MIGRATION",
          "description": "string"
        },
        "peerDetails": {
          "firstName": "John",
          "lastName": "Doe"
        },
        "instrumentDetails": {
          "instrumentId": "123456789",
          "instrumentType": "CARD"
        }
      }
    ]
  },
  "recipient": {
    "accountId": "5014567344",
    "customerId": "5435323362",
    "slipId": "5009964049",
    "transactions": [
      {
        "id": "544232",
        "slipId": "5009964049",
        "customerId": "5435323362",
        "accountId": "212345",
        "type": "DEPOSIT",
        "amount": 1000,
        "currencyCode": "EUR",
        "fees": [
          {
            "amount": 1000,
            "currency": "EUR",
            "paymentReason": "OTHER_FEE"
          }
        ],
        "creationTime": "2021-07-15T17:54:12Z",
        "lastChangeDate": "2021-07-15T17:54:12Z",
        "direction": "CREDIT",
        "paymentType": "CARD",
        "status": "COMPLETED",
        "statusReason": "string",
        "merchantRefNum": "af5c8b52-0afd-4799-85ab-fe659a076932",
        "balance": 0,
        "recipientReference": "string",
        "fxAmount": {
          "amount": 0,
          "rate": 0,
          "currency": "EUR"
        },
        "transferDetails": {
          "reason": "INITIAL_BALANCE_MIGRATION",
          "description": "string"
        },
        "peerDetails": {
          "firstName": "John",
          "lastName": "Doe"
        },
        "instrumentDetails": {
          "instrumentId": "123456789",
          "instrumentType": "CARD"
        }
      }
    ]
  },
  "merchantRefNum": "5040452805",
  "reason": "INITIAL_BALANCE_MIGRATION",
  "fxQuote": "string",
  "transferDetails": {
    "reason": "INITIAL_BALANCE_MIGRATION",
    "description": "string"
  },
  "id": "5000000123",
  "slipId": "5009964049",
  "merchant": {
    "accountId": "5014567344",
    "customerId": "5435323362",
    "slipId": "5009964049",
    "transactions": [
      {
        "id": "544232",
        "slipId": "5009964049",
        "customerId": "5435323362",
        "accountId": "212345",
        "type": "DEPOSIT",
        "amount": 1000,
        "currencyCode": "EUR",
        "fees": [
          {
            "amount": 1000,
            "currency": "EUR",
            "paymentReason": "OTHER_FEE"
          }
        ],
        "creationTime": "2021-07-15T17:54:12Z",
        "lastChangeDate": "2021-07-15T17:54:12Z",
        "direction": "CREDIT",
        "paymentType": "CARD",
        "status": "COMPLETED",
        "statusReason": "string",
        "merchantRefNum": "af5c8b52-0afd-4799-85ab-fe659a076932",
        "balance": 0,
        "recipientReference": "string",
        "fxAmount": {
          "amount": 0,
          "rate": 0,
          "currency": "EUR"
        },
        "transferDetails": {
          "reason": "INITIAL_BALANCE_MIGRATION",
          "description": "string"
        },
        "peerDetails": {
          "firstName": "John",
          "lastName": "Doe"
        },
        "instrumentDetails": {
          "instrumentId": "123456789",
          "instrumentType": "CARD"
        }
      }
    ]
  },
  "status": "COMPLETED"
}

{
  "amount": 1000,
  "fee": 100,
  "currencyCode": "GBP",
  "sender": {
    "customerId": "5435323362",
    "accountId": "5014567344"
  },
  "recipient": {
    "customerId": "99999",
    "accountId": "999991"
  },
  "merchantRefNum": "5040452805",
  "status": "PENDING"
}

{
  "amount": 1000,
  "fee": 100,
  "currencyCode": "GBP",
  "sender": {
    "customerId": "99999",
    "accountId": "999991"
  },
  "recipient": {
    "customerId": "500014306996",
    "accountId": "5014567344"
  },
  "merchantRefNum": "5040452805",
  "status": "PENDING"
}

{
  "amount": 1000,
  "fee": 100,
  "currencyCode": "GBP",
  "sender": {
    "customerId": "500014306996"
  },
  "recipient": {
    "customerId": "500014306997",
    "accountId": "5014567346"
  },
  "merchantRefNum": "5040452805",
  "status": "PENDING"
}

{
  "amount": 1000,
  "fee": 100,
  "currencyCode": "GBP",
  "sender": {
    "customerId": "500014306996",
    "accountId": "5014567344"
  },
  "recipient": {
    "customerId": "99999",
    "accountId": "999991"
  },
  "merchantRefNum": "5040452805",
  "status": "PENDING"
}

Bad Request

application/json

Schema
Example (from schema)

Schema

error

object

Represents details of an error.

code string

The error code.

message string

The description of the error.

details string[]

Details for the errors of any parameter value.

fieldErrors

object[]

List of field errors associated with the main error.

Array [

field string

Identifies the JSON request field.

error string

The problem associated with the field.

]

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ],
    "fieldErrors": [
      {
        "field": "string",
        "error": "string"
      }
    ]
  }
}

Transfer funds to wallet recipient

/transfers

Introduction​

Currency conversion​

Customer-to-merchant transfer​

Merchant-to-customer transfer​

Customer-to-customer transfer​

Transfer Async behavior​

Merchant Fee collection​

Request​

Header Parameters

Body

Responses​

Introduction

Currency conversion

Customer-to-merchant transfer

Merchant-to-customer transfer

Customer-to-customer transfer

Transfer Async behavior

Merchant Fee collection

Request

Responses