Create Withdrawal
POST/v2/customers/:customerId/withdrawals
Create withdrawal for the current customer.
Withdrawals are created in PREVIEW
state.
The following parameters are required:
- currency - withdrawal currency
- amount - withdrawal amount in currency minor units
- paymentOption - withdrawal payment option must be one of the available payment options provided by
GET /profile/withdrawals/options
- paymentInstrumentReference - provide reference to existing verified payment instrument provided by
GET /profile/instruments
- deviceInfo - should provide valide appType and profiling session id.
Optional parameters:
- merchantRefNum - should be provided by the partner if he desires to match with objects in his backend system.
Withdrawals in PREVIEW state do not create actual transaction in Paysafe Wallet system. It allows to check withdrawal parameters and display the fees.
To move the payment forward you must request status change using POST /profile/withdrawals/{withdrawalId}/status
. This will perform the required validations and move the withdrawal in PENDING
state.
{
"status": "PENDING"
}
To confirm the withdrawal for execution use POST /profile/withdrawals/{withdrawalId}/status
:
{
"status": "PROCESSING"
}
Request
Path Parameters
Customer Id.
- application/json
Body
required
Array [
- CARD_CVV - Card CVV is required to confirm the card payment during deposit.
- Valid value:
123
- Valid value:
- CARD_SAVE_INSTRUMENT - The user agrees to save the card for further payments.
- Valid value:
true
- Valid value:
- PAYMENT_CONFIRMATION - For PCI-DSS level 3 partners card information is collected in Paysafe hosted interface. |Valid values|Description| |---|---| |EMBEDDED|Default The payment is confirmed in the hosted Paysafe interface | |OUTSOURCED| The payment flow is returned to caller after collection of card data|
]
Array [
- 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
]
withdrawal amount in currency minor units.
Possible values: >= 3 characters
and <= 3 characters
Currency alphabetic code as specified by ISO 4217
paymentInstrumentReference
object
Represents a reference to a Payment Instrument, used for Deposit or Withdrawal.
Instrument identifier.
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 |
Possible values: <= 255 characters
This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request and allows cross referencing objects from merchant system to embedded wallet objects.
deviceInfo
object
Provides information about the device that the end-customer uses to access the service.
Possible values: [WEB_APP
, MOBILE_APP
, API
]
Possible values: <= 100 characters
ThreatMetrics session id.
Customer IP Address.
paymentProperties
object[]
List of payment option specific properties.
Possible values: [CARD_CVV
, CARD_SAVE_INSTRUMENT
, SAVE_RECIPIENT
, PAYMENT_CONFIRMATION
]
Payment property key. Defines available payment property key and their meaning.
Card payment properties:
The value of the payment property.
Possible values: [RAPID_TRANSFER
, BANK_TRANSFER
, CARD
, PAYSAFECASH
, PAGO_EFECTIVO
]
Payment option requested by customer.
fees
object[]
Customer fees attached to the transaction.
Default value: 0
Amount of the merchant payment, in mintor units. If currency
is not specified, then the main transaction currency is used.
Possible values: >= 3 characters
and <= 3 characters
Currency alphabetic code as specified by ISO 4217
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.
The target merchant wallet id.
Possible values: >= 3 characters
and <= 3 characters
Currency alphabetic code as specified by ISO 4217
The target account in which the payment is accepted. If not specified the account is determined by the main transaction currency.
Possible values: [THIRD_PARTY
, FIRST_PARTY
]
Default value: FIRST_PARTY
Participant in the payment.
Possible values: <= 50 characters
Description of the payment.
Withdrawal recipient id of ACTIVE withdrawal recipient for THIRD_PARTY withdrawals. If not specified during THIRD_PARTY Withdrawal creation, the withdrawal recipient must be specified during the first withdrawal step.
Responses
- 201
- 400
- 405
Created
- application/json
- Schema
- Example (from schema)
- BANK_WITHDRAWAL_PREVIEW
- CARD_WITHDRAWAL_PREVIEW
- BANK_PENDING_WITHDRAWAL
- BANK_COMPLETED_WITHDRAWAL
- CARD_COMPLETED_WITHDRAWAL
- CARD_PENDING_WITHDRAWAL
- CCI_BANK_ACCOUNT_PREVIEW
Schema
Array [
- CARD_CVV - Card CVV is required to confirm the card payment during deposit.
- Valid value:
123
- Valid value:
- CARD_SAVE_INSTRUMENT - The user agrees to save the card for further payments.
- Valid value:
true
- Valid value:
- PAYMENT_CONFIRMATION - For PCI-DSS level 3 partners card information is collected in Paysafe hosted interface. |Valid values|Description| |---|---| |EMBEDDED|Default The payment is confirmed in the hosted Paysafe interface | |OUTSOURCED| The payment flow is returned to caller after collection of card data|
]
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 cancelledREFUNDED
- Payment has been refunded. Valid only for deposits.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.-
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.
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.Array [
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.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.]
Array [
PAYSAFECASH_BARCODE_TYPE
- The type of the generated barcode, when using the Paysafecash payment option.- Valid value:
CODE128
- Valid value:
PAYSAFECASH_BARCODE_VALUE
- The value of the generated barcode, when using the Paysafecash payment option.- Valid value:
1000000000000004574
- Valid value:
]
Array [
- 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
]
withdrawal amount in currency minor units.
Possible values: >= 3 characters
and <= 3 characters
Currency alphabetic code as specified by ISO 4217
paymentInstrumentReference
object
Represents a reference to a Payment Instrument, used for Deposit or Withdrawal.
Instrument identifier.
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 |
Possible values: <= 255 characters
This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request and allows cross referencing objects from merchant system to embedded wallet objects.
paymentProperties
object[]
List of payment option specific properties.
Possible values: [CARD_CVV
, CARD_SAVE_INSTRUMENT
, SAVE_RECIPIENT
, PAYMENT_CONFIRMATION
]
Payment property key. Defines available payment property key and their meaning.
Card payment properties:
The value of the payment property.
Withdrawal id generated during creation.
Slip identifier. Slip contains list of transactions associated with the withdrawal operations.
Withdrawal funding transaction id.
Represents RFC 3339, section 5.6 date-time.
Represents RFC 3339, section 5.6 date-time.
Possible values: [PREVIEW
, PENDING
, PROCESSING
, COMPLETED
, FAILED
, CANCELLED
, REFUNDED
]
The payment status:
Possible values: <= 60 characters
Status reason for FAILED transaction.
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.
Possible values: [NONE
, REDIRECT
, SCA
]
Default value: NONE
Specifies action required to complete to be able to continue to the next payment status:
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.
The distinct identifier for the SCA authentication event.
The distinct identifier for the wallet operation. This identifier is used to associate the wallet operation with the SCA authentication event.
Possible values: [OUTSOURCED
, EMBEDDED
, HYBRID
]
Mode of the Strong Customer Authentication (SCA) authentication process.
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.
Possible values: [PASSWORD
, PIN
, PASSKEYS
, OTP
, BIOMETRIC
]
Method used for verifying the SCA authentication event attempt.
Possible values: [SMS
, EMAIL
, AUTHENTICATOR
, PUSH_NOTIFICATION
]
Channel used to send the verification method to the user.
The destination for the verification mechanism (when available), such as the phone number or email address where the verification value will be delivered.
Represents RFC 3339, section 5.6 date-time.
Represents RFC 3339, section 5.6 date-time.
Possible values: [RAPID_TRANSFER
, BANK_TRANSFER
, OFFLINE_BANK_TRANSFER
, CARD
, PAYSAFECASH
, PAGO_EFECTIVO
]
Enumeration of supported Payment Option Types
paymentDetails
object[]
List of payment-option-specific details.
Possible values: [PAYSAFECASH_BARCODE_TYPE
, PAYSAFECASH_BARCODE_VALUE
]
Defines the available payment details keys and their meaning.
Paysafecash-specific details:
Possible values: [THIRD_PARTY
, FIRST_PARTY
]
Default value: FIRST_PARTY
Participant in the payment.
Possible values: <= 50 characters
Description of the payment.
Withdrawal recipient id of ACTIVE withdrawal recipient for THIRD_PARTY withdrawals. If not specified during THIRD_PARTY Withdrawal creation, the withdrawal recipient must be specified during the first withdrawal step.
fees
object[]
Customer fees attached to the transaction.
Default value: 0
Amount of the merchant payment, in mintor units. If currency
is not specified, then the main transaction currency is used.
Possible values: >= 3 characters
and <= 3 characters
Currency alphabetic code as specified by ISO 4217
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.
The target merchant wallet id.
Possible values: >= 3 characters
and <= 3 characters
Currency alphabetic code as specified by ISO 4217
The target account in which the payment is accepted. If not specified the account is determined by the main transaction currency.
fxAmount
object
(In Development)
Contains the amount in converted currency during currency conversion.
Converted amount (in minor units).
Currency conversion rate.
Possible values: >= 3 characters
and <= 3 characters
Currency alphabetic code as specified by ISO 4217
{
"amount": 1000,
"currencyCode": "EUR",
"paymentInstrumentReference": {
"id": "1001",
"instrumentType": "CARD"
},
"merchantRefNum": "4bc2deb3-9766-4598-a08e-a98b60615936",
"paymentProperties": [
{
"key": "CARD_CVV",
"value": "string"
}
],
"id": "5000000123",
"accountId": "1000000123",
"customerId": "2000000123",
"slipId": "5009964049",
"fundingTransactionId": "544232",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T17:54:12Z",
"status": "COMPLETED",
"statusReason": "string",
"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"
},
"paymentOption": "CARD",
"paymentDetails": [
{
"key": "PAYSAFECASH_BARCODE_TYPE",
"value": "string"
}
],
"type": "FIRST_PARTY",
"description": "string",
"recipientReference": "97266b06-c85f-4acd-9a3f-3aa0eed8b11e",
"fees": [
{
"amount": 1000,
"currency": "EUR",
"paymentReason": "OTHER_FEE",
"merchantId": "500005",
"recipientCurrency": "EUR",
"merchantAccountId": "100001",
"fxAmount": {
"amount": 0,
"rate": 0,
"currency": "EUR"
}
}
]
}
{
"id": "124567",
"amount": 1000,
"currencyCode": "USD",
"paymentOption": "BANK_TRANSFER",
"paymentInstrumentReference": {
"id": "12345",
"instrumentType": "US_BANK_ACCOUNT"
},
"accountId": "5009964049",
"customerId": "500014306996",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T18:54:12Z",
"fee": 100,
"fees": [
{
"amount": 100,
"currency": "USD",
"paymentReason": "MERCHANT_FEE"
}
],
"status": "PREVIEW"
}
{
"id": "5040057610",
"amount": 1000,
"currencyCode": "EUR",
"paymentOption": "CARD",
"paymentInstrumentReference": {
"id": "34345",
"instrumentType": "CARD"
},
"customerId": "500000001",
"accountId": "500000011",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T18:54:12Z",
"fee": 100,
"fees": [
{
"amount": 100,
"currency": "EUR",
"paymentReason": "MERCHANT_FEE"
}
],
"status": "PREVIEW"
}
{
"amount": 1000,
"currencyCode": "USD",
"paymentOption": "BANK_TRANSFER",
"paymentInstrumentReference": {
"id": "12345",
"instrumentType": "US_BANK_ACCOUNT"
},
"id": "5000000123",
"accountId": "1000000123",
"customerId": "2000000123",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T17:54:12Z",
"fee": 100,
"fees": [
{
"amount": 100,
"currency": "USD",
"paymentReason": "MERCHANT_FEE"
}
],
"fundingTransactionId": "544232",
"slipId": "5009964049",
"status": "PENDING"
}
{
"amount": 1000,
"currencyCode": "USD",
"paymentOption": "BANK_TRANSFER",
"paymentInstrumentReference": {
"id": "12345",
"instrumentType": "US_BANK_ACCOUNT"
},
"id": "5000000123",
"accountId": "1000000123",
"customerId": "2000000123",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T17:54:12Z",
"fee": 100,
"fees": [
{
"amount": 100,
"currency": "USD",
"paymentReason": "MERCHANT_FEE"
}
],
"fundingTransactionId": "544232",
"slipId": "5009964049",
"status": "COMPLETED"
}
{
"amount": 1000,
"currencyCode": "EUR",
"paymentOption": "CARD",
"paymentInstrumentReference": {
"id": "123",
"instrumentType": "CARD"
},
"id": "5000000123",
"accountId": "1000000123",
"customerId": "2000000123",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T17:54:12Z",
"fee": 100,
"fees": [
{
"amount": 100,
"currency": "EUR",
"paymentReason": "MERCHANT_FEE"
}
],
"fundingTransactionId": "544232",
"slipId": "5009964049",
"status": "COMPLETED"
}
{
"amount": 1000,
"currencyCode": "EUR",
"paymentOption": "CARD",
"paymentInstrumentReference": {
"id": "123",
"instrumentType": "CARD"
},
"id": "5000000123",
"accountId": "1000000123",
"customerId": "2000000123",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T17:54:12Z",
"fee": 100,
"fees": [
{
"amount": 100,
"currency": "EUR",
"paymentReason": "MERCHANT_FEE"
}
],
"fundingTransactionId": "544232",
"slipId": "5009964049",
"status": "PENDING"
}
{
"amount": 1000,
"currencyCode": "EUR",
"paymentOption": "BANK_TRANSFER",
"paymentInstrumentReference": {
"id": "123",
"instrumentType": "CCI_BANK_ACCOUNT"
},
"id": "5000000123",
"accountId": "1000000123",
"customerId": "2000000123",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T17:54:12Z",
"fee": 100,
"fees": [
{
"amount": 100,
"currency": "EUR",
"paymentReason": "MERCHANT_FEE"
}
],
"fundingTransactionId": "544232",
"slipId": "5009964049",
"status": "PREVIEW"
}
Bad Request
- application/json
- Schema
- Example (from schema)
- INVALID_WITHDRAWAL_ACCOUNT
Schema
Array [
]
error
object
Represents details of an error.
The error code.
The description of the error.
Details for the errors of any parameter value.
fieldErrors
object[]
List of field errors associated with the main error.
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "DW-INVALID-WITHDRAW-ACCOUNT",
"message": "Withdrawal from this account is not supported.",
"details": [
""
]
}
}
Method Not Allowed
- application/json
- Schema
- Example (from schema)
- DW-OPERATION-NOT-ALLOWED
Schema
Array [
]
error
object
Represents details of an error.
The error code.
The description of the error.
Details for the errors of any parameter value.
fieldErrors
object[]
List of field errors associated with the main error.
Identifies the JSON request field.
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."
]
}
}