Transfer funds to wallet recipient

POST /v2/customers/:customerId/transfers

Introduction

A transfer is the movement of funds between two wallet accounts. It allows peer to peer transfer to another wallet user. Transfer requires the following parameters:

amount - the amount in minor units
currencyCode - currency of the amount
email or customerId of the recipient
deviceInfo - device profiling information

For successful transfer the following conditions must be met:

Customer should have enough balance in the requested currency
Recipient customer must exist in the system and must not be restricted

Transfer Execution

Transfer is created in PREVIEW state, which can be used to determine the recipient and FX amount (if applicable).

To move forward the execution you should usе the POST /v2/customers/{customerId}/transfers/{transferId}/status to prepare the transfer for execution.

{
   "status": "PENDING"
}

This will create a PENDING transaction and associate it with the transfer. All limits and other checks will be performed.

To confirm the transfer for execution POST /v2/customers/{customerId}/transfers/{transferId}/status:

{
   "status": "PROCESSING"
}

The transfers are executed asynchronously. Check the transfer status for details.

Using transfers for local currency exchange

If customer want to exchange currency between his accounts, he must provide FX Quote parameter and skip the recipient parameter.

The following conditions must be met:

have account in the targetCurrency of the FX Quote
enough balance in the sourceCurrency

Merchant Fee collection

(In Development)

A fee can be collected by the merchant for the transfer. Fees are collected in preconfigured merchant fee collection account in the corresponding fee currency. Supported fee payment reasons are SENDER_FEE and RECIPIENT_FEE.

`SENDER_FEE`	`RECIPIENT_FEE`
Fee amount is added on top of the request amount.	Fee is deducted from request amount.
Sender is charged.	Recipient is charged.

Request

Path Parameters

customerId stringrequired

application/json

Body

required

amount int64required

Transaction amount in minor units.

currencyCode Currency (string)required

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

Currency alphabetic code as specified by ISO 4217

recipient

object

Contains transfer recipient information. If used in CustomerTransferRequest context, the system tries to resolve email to customerId in the system.

customerId string

email email

Possible values: <= 150 characters

merchantRefNum string

Possible values: <= 50 characters

Merchant reference number associated with the transaction.

deviceInfo

object

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

appType stringrequired

Possible values: [WEB_APP, MOBILE_APP, API]

threatMetrixSessionId string

Possible values: <= 100 characters

ThreatMetrics session id.

customerIp string

Customer IP Address.

fxQuote string

(In Development) FX Quote ID for the transfer in case currency conversion is required. If not passed currency conversion is not perfomed.

transferDetails

object

required

Represents the details of a transfer.

reason TransferReason (string)required

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

description string

Possible values: <= 200 characters

Human readable description for the transfer.

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

merchantId string

The target merchant wallet id.

recipientCurrency Currency (string)

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

Currency alphabetic code as specified by ISO 4217

merchantAccountId string

The target account in which the payment is accepted. If not specified the account is determined by the main transaction currency.

]

Responses

Accepted

application/json

Schema
Example (from schema)
EXCHANGE_TRANSFER_PREVIEW
PEER_TRANSFER_PREVIEW

Schema

amount int64required

Transaction amount in minor units.

currencyCode Currency (string)required

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

Currency alphabetic code as specified by ISO 4217

recipient

object

Contains transfer recipient information. If used in CustomerTransferRequest context, the system tries to resolve email to customerId in the system.

customerId string

email email

Possible values: <= 150 characters

merchantRefNum string

Possible values: <= 50 characters

Merchant reference number associated with the transaction.

fxQuote string

(In Development) FX Quote ID for the transfer in case currency conversion is required. If not passed currency conversion is not perfomed.

transferDetails

object

required

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 stringrequired

The transfer id

fee int64deprecated

Transaction fee in minor units. The field is deprecated. Please use fees field instead.

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-timerequired

Represents RFC 3339, section 5.6 date-time.

expirationTime date-time

Represents RFC 3339, section 5.6 date-time.

status Payment Status (string)required

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

The payment status:

PREVIEW - Payment preview.
PENDING - Payment transaction is created and further action is required by the customer.
PROCESSING - Payment is scheduled for processing by the payment provider.
COMPLETED - Payment 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 - Payment has failed. Check STATUS_REASON property for details.
CANCELLED - Payment have been cancelled
REFUNDED - Payment has been refunded. Valid only for deposits.

statusReason string

Possible values: <= 60 characters

Status reason for FAILED transaction.

sender

object

Contains transfer sender information

customerId string

accountId string

slipId string

Slip identifier. Slip contains list of transactions associated with the transfer operation.

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

nextStatus Payment Status (string)[]

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

Provides the next possible status update the client can request, depending on the chosen payment type and option.

action Payment Action (string)

Possible values: [NONE, REDIRECT, SCA]

Default value: NONE

Specifies action required to complete to be able to continue to the next payment status:

NONE – No action is required, you can proceed to the next deposit status.
REDIRECT – The user must be redirected in order to complete a payment, for example, when an alternate payment method like Paysafecard is used.
SCA - The user must complete a Strong Customer Authentication (SCA) process.

scaDetails

object

SCA authentication details, including information about the authentication process. It should be present in the response of any wallet operation that requires it due to PSD2 regulatory requirements.

Present in the response - operation requires SCA authentication, and the user should proceed with the SCA process.
Not present in the response - operation does not require SCA authentication and is authorized to proceed.

eventId stringrequired

The distinct identifier for the SCA authentication event.

walletOperationId stringrequired

The distinct identifier for the wallet operation. This identifier is used to associate the wallet operation with the SCA authentication event.

authenticationMode SCA Authentication Mode (string)required

Possible values: [OUTSOURCED, EMBEDDED, HYBRID]

Mode of the Strong Customer Authentication (SCA) authentication process.

OUTSOURCED - The partner is responsible for handling the entire SCA process.
EMBEDDED - Paysafe is responsible for handling the entire SCA process, including user authentication and compliance with regulations like PSD2.
HYBRID - Paysafe manages the entire SCA process, excluding the communication with the end-user.

availableVerifications

object[]

List of available verifications for the SCA authentication event. If none are specified, the user can proceed with any agreed-upon verification method.

Array [

method SCA Authentication Event Attempt Verification Method (string)required

Possible values: [PASSWORD, PIN, PASSKEYS, OTP, BIOMETRIC]

Method used for verifying the SCA authentication event attempt.

PASSWORD - A secret combination of characters, typically chosen by the user, used to authenticate their identity.
PIN - A numeric code, typically six digits, used to authenticate the user's identity.
PASSKEYS - A set of predefined keys or a pattern chosen by the user to authenticate their identity.
OTP - One-Time Password sent via SMS, email, or authenticator application to the user's registered device.
BIOMETRIC - Authentication based on unique physical characteristics of the user, such as fingerprint, facial recognition, or iris scan.

channel SCA Authentication Event Attempt Verification Channel (string)

Possible values: [SMS, EMAIL, AUTHENTICATOR, PUSH_NOTIFICATION]

Channel used to send the verification method to the user.

SMS - Verification method sent via SMS to the user's registered device.
EMAIL - Verification method sent via email to the user's registered address.
AUTHENTICATOR - Verification method generated by an authenticator application installed on the user's device.
PUSH_NOTIFICATION - Verification method sent via the user's mobile device prompting them to approve or deny the authentication request.

target string

The destination for the verification mechanism (when available), such as the phone number or email address where the verification value will be delivered.

]

creationTime date-timerequired

Represents RFC 3339, section 5.6 date-time.

expirationTime date-time

Represents RFC 3339, section 5.6 date-time.

{
  "amount": 1000,
  "currencyCode": "EUR",
  "recipient": {
    "customerId": "string",
    "email": "user@example.com"
  },
  "merchantRefNum": "5040452805",
  "fxQuote": "string",
  "transferDetails": {
    "reason": "INITIAL_BALANCE_MIGRATION",
    "description": "string"
  },
  "id": "12356",
  "fees": [
    {
      "amount": 1000,
      "currency": "EUR",
      "paymentReason": "OTHER_FEE"
    }
  ],
  "creationTime": "2021-07-15T17:54:12Z",
  "expirationTime": "2021-07-15T17:54:12Z",
  "status": "COMPLETED",
  "statusReason": "string",
  "sender": {
    "customerId": "string",
    "accountId": "string"
  },
  "slipId": "string",
  "fxAmount": {
    "amount": 0,
    "rate": 0,
    "currency": "EUR"
  },
  "nextStatus": [
    "COMPLETED"
  ],
  "action": "NONE",
  "scaDetails": {
    "eventId": "06bdcd2c-0cce-4b36-97ec-281c8f5d743c",
    "walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36",
    "authenticationMode": "OUTSOURCED",
    "availableVerifications": [
      {
        "method": "OTP",
        "channel": "SMS",
        "target": "jo***@example.com"
      }
    ],
    "creationTime": "2021-07-15T17:54:12Z",
    "expirationTime": "2021-07-15T17:54:12Z"
  }
}

{
  "amount": 1000,
  "currencyCode": "GBP",
  "recipient": {
    "customerId": "5435323362",
    "email": "user@example.com"
  },
  "fxQuote": "404679be-ccbf-4528-b880-e14cc5041753",
  "transferDetails": {
    "reason": "CURRENCY_EXCHANGE",
    "description": "Exchange money"
  },
  "id": "12356",
  "fee": 100,
  "fees": [
    {
      "amount": 100,
      "currency": "GBP",
      "paymentReason": "MERCHANT_FEE"
    }
  ],
  "creationTime": "2021-07-15T17:54:12Z",
  "expirationTime": "2021-07-15T17:54:12Z",
  "status": "PREVIEW",
  "fxAmount": {
    "amount": 1035,
    "rate": 1.15,
    "currency": "EUR"
  }
}

{
  "amount": 1000,
  "currencyCode": "EUR",
  "recipient": {
    "customerId": "5435323363",
    "email": "user@example.com"
  },
  "merchantRefNum": "5040452805",
  "transferDetails": {
    "reason": "PEER_TRANSFER",
    "description": "Transfer to friend."
  },
  "id": "12356",
  "fee": 100,
  "fees": [
    {
      "amount": 100,
      "currency": "EUR",
      "paymentReason": "MERCHANT_FEE"
    }
  ],
  "creationTime": "2021-07-15T17:54:12Z",
  "expirationTime": "2021-07-15T17:54:12Z",
  "status": "PREVIEW"
}

Bad Request

application/json

Schema
Example (from schema)
TRANSFER_LIMIT_EXCEEDED

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"
      }
    ]
  }
}

{
  "error": {
    "code": "TRANSFER_LIMIT_EXCEEDED",
    "message": "Transfer limit exceeded",
    "details": [
      ""
    ]
  }
}

Method Not Allowed

application/json

Schema
Example (from schema)
DW-OPERATION-NOT-ALLOWED

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"
      }
    ]
  }
}

{
  "error": {
    "code": "DW-OPERATION-NOT-ALLOWED",
    "message": "Operation is not allowed in your account. Contact Paysafe for further details.",
    "details": [
      "Operation is not allowed in your account. Contact Paysafe for further details."
    ]
  }
}

Transfer funds to wallet recipient

/v2/customers/:customerId/transfers

Introduction​

Transfer Execution​

Using transfers for local currency exchange​

Merchant Fee collection​

Request​

Path Parameters

Body

Responses​

Introduction

Transfer Execution

Using transfers for local currency exchange

Merchant Fee collection

Request

Responses