Process Withdrawal

POST 
/v2/customers/:customerId/withdrawals/:withdrawalId/status

Request withdrawal status update.

Withdrawals are created in PREVIEW state. 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

withdrawalId stringrequired

The unique id of the withdrawal.

customerId stringrequired

application/json

Body

status PaymentStatus (string)required

Possible values: [PENDING, PROCESSING]

paymentProperties

object[]

List of payment option specific properties required for processing of the payment.

Array [

key PaymentPropertyKey (string)

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:

• CARD_CVV - Card CVV is required to confirm the card payment during deposit.
  • Valid value: 123
• CARD_SAVE_INSTRUMENT - The user agrees to save the card for further payments.
  • Valid value: true
• 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|

value string

The value of the payment property.

]

recipient

object

Withdrawal recipient request object.

label string

Possible values: non-empty and <= 100 characters

Label for the recipient. Use this field to label the recipient, if you want to make additional payments to the same party. If not specified the label is generated by combining the title, first name, and last name. If ACTIVE recipient with the same label already exists a number suffix is added.

title string

Possible values: <= 15 characters

Personal title, Mr., Dr., etc.

firstName stringrequired

Possible values: non-empty and <= 50 characters

First name. Only latin characters, spaces, single quotes, and hyphens are allowed.

lastName stringrequired

Possible values: non-empty and <= 50 characters

Last name. Only latin characters, spaces, single quotes, and hyphens are allowed.

address

object

required

Address of the customer.

countryCode CountryCode (string)required

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

ISO-3166 Alpha 2

stateProvince string

Possible values: <= 2 characters

US state postal abbreviation. Not used for non-US territories.

city stringrequired

Possible values: <= 50 characters

City.

postalCode stringrequired

Possible values: non-empty and <= 50 characters

Postal code.

address1 stringrequired

Possible values: <= 200 characters

The first line of the address.

address2 string

Possible values: <= 200 characters

The second line of the address.

contactInfo

object

Represents contact information.

mobile string

Possible values: <= 50 characters

Mobile number.

email email

Possible values: >= 6 characters and <= 100 characters

Email.

paymentInstrument

object

required

Represents a payment instrument, used for third-party payments. Here are the valid instrumentType values:

• SEPA_BANK_ACCOUNT - IBAN Bank Account for EEA international transfers

• UK_BANK_ACCOUNT - UK Bank Account for somestic UK transfers

• US_BANK_ACCOUNT - US Bank Account for domestic USA transfers

instrumentType

string

required

Possible values: [SEPA_BANK_ACCOUNT, UK_BANK_ACCOUNT, US_BANK_ACCOUNT]

Represents the type of the recipient instrument.

Value	Description
SEPA_BANK_ACCOUNT	SEPA Bank account
UK_BANK_ACCOUNT	UK Bank account
US_BANK_ACCOUNT	US Bank account

SEPA_BANK_ACCOUNT

accountHolderName string

Possible values: <= 100 characters

This is the name of the customer or company that owns the bank account.

iban stringrequired

The International Bank Account Number (IBAN) of the account.

bic stringrequired

The Bank Account Bank Identifier Code (BIC) code. Also known as SWIFT code.

UK_BANK_ACCOUNT

accountHolderName string

Possible values: <= 100 characters

This is the name of the customer or company that owns the bank account.

accountNumber stringrequired

The bank account number.

sortCode stringrequired

Use our sort code checker to easily find and check UK sort codes.

bankName string

The bank name.

US_BANK_ACCOUNT

accountHolderName string

Possible values: <= 100 characters

This is the name of the customer or company that owns the bank account. As per regulations, the Wallet holder and bank account holder must be the same.

accountNumber stringrequired

Possible values: >= 4 characters and <= 17 characters

The bank account number.

routingNumber stringrequired

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

For USD accounts, this is the 9-digit routing number of the bank.

accountType string

Possible values: [SAVINGS, CHECKING, LOAN]

The account type.

type stringrequired

Possible values: [BUSINESS, INDIVIDUAL]

Recipient type.

scaDetails

object

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

• Included in the request - operation has already undergone SCA authentication and is authorized to proceed. The SCA details connect the wallet operation to the SCA authentication event.

• Not included in the request - operation either does not require SCA authentication or is being initiated for the first time, and the user's need for SCA is uncertain. If SCA is needed, the response will provide the SCA details for use in the subsequent execution of the wallet operation.

eventId stringrequired

A distinct identifier for the SCA authentication event.

walletOperationId stringrequired

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

Responses

202

Accepted

application/json

Schema

Schema

amount int64required

withdrawal amount in currency minor units.

currencyCode Currency (string)required

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.

id stringrequired

Instrument identifier.

instrumentType InstrumentType (string)required

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 |

merchantRefNum MerchantReferenceNumber (string)

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.

Array [

key PaymentPropertyKey (string)

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:

• CARD_CVV - Card CVV is required to confirm the card payment during deposit.
  • Valid value: 123
• CARD_SAVE_INSTRUMENT - The user agrees to save the card for further payments.
  • Valid value: true
• 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|

value string

The value of the payment property.

]

id stringrequired

Withdrawal id generated during creation.

accountId stringrequired
customerId stringrequired
slipId string

Slip identifier. Slip contains list of transactions associated with the withdrawal operations.

fundingTransactionId string

Withdrawal funding transaction id.

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.

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.

paymentOption PaymentOptionType (string)

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.

Array [

key PaymentDetailsKey (string)

Possible values: [PAYSAFECASH_BARCODE_TYPE, PAYSAFECASH_BARCODE_VALUE]

Defines the available payment details keys and their meaning.

Paysafecash-specific details:

• PAYSAFECASH_BARCODE_TYPE - The type of the generated barcode, when using the Paysafecash payment option.
  • Valid value: CODE128
• PAYSAFECASH_BARCODE_VALUE - The value of the generated barcode, when using the Paysafecash payment option.
  • Valid value: 1000000000000004574

value string

]

type ParticipantType (string)

Possible values: [THIRD_PARTY, FIRST_PARTY]

Default value: FIRST_PARTY

Participant in the payment.

description string

Possible values: <= 50 characters

Description of the payment.

recipientReference string

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.

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.

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

]

Example (from schema)

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

US_BANK_ACCOUNT_WITHDRAW

{
  "amount": 1000,
  "currencyCode": "USD",
  "paymentOption": "BANK_TRANSFER",
  "paymentInstrumentReference": {
    "id": "12345",
    "instrumentType": "US_BANK_ACCOUNT"
  },
  "id": "124567",
  "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": "PENDING",
  "nextStatus": [
    "PROCESSING"
  ],
  "action": "NONE"
}

US_BANK_ACCOUNT_WITHDRAW_SCA_REQUIRED

{
  "amount": 1000,
  "currencyCode": "USD",
  "paymentOption": "BANK_TRANSFER",
  "paymentInstrumentReference": {
    "id": "12345",
    "instrumentType": "US_BANK_ACCOUNT"
  },
  "id": "124567",
  "accountId": "5009964049",
  "customerId": "500014306996",
  "creationTime": "2021-07-15T17:54:12Z",
  "expirationTime": "2021-07-15T18:54:12Z",
  "status": "PENDING",
  "nextStatus": [
    "PROCESSING"
  ],
  "action": "SCA",
  "scaDetails": {
    "eventId": "06bdcd2c-0cce-4b36-97ec-281c8f5d743c",
    "walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36",
    "authenticationMode": "OUTSOURCED",
    "availableVerifications": [
      {
        "method": "PIN"
      },
      {
        "method": "OTP",
        "channel": "SMS"
      }
    ],
    "creationTime": "2021-07-15T17:54:12Z",
    "expirationTime": "2021-07-15T18:09:12Z"
  },
  "fee": 100,
  "fees": [
    {
      "amount": 100,
      "currency": "USD",
      "paymentReason": "MERCHANT_FEE"
    }
  ]
}

CCI_BANK_ACCOUNT_WITHDRAW_PENDING

{
  "amount": 1000,
  "currencyCode": "USD",
  "paymentOption": "BANK_TRANSFER",
  "paymentInstrumentReference": {
    "id": "12345",
    "instrumentType": "CCI_BANK_ACCOUNT"
  },
  "id": "124567",
  "accountId": "5009964049",
  "customerId": "500014306996",
  "creationTime": "2021-07-15T17:54:12Z",
  "expirationTime": "2021-07-15T18:54:12Z",
  "status": "PENDING",
  "nextStatus": [
    "PROCESSING"
  ],
  "action": "NONE"
}

CCI_BANK_ACCOUNT_WITHDRAW_PROCESSING

{
  "amount": 1000,
  "currencyCode": "USD",
  "paymentOption": "BANK_TRANSFER",
  "paymentInstrumentReference": {
    "id": "12345",
    "instrumentType": "CCI_BANK_ACCOUNT"
  },
  "id": "124567",
  "accountId": "5009964049",
  "customerId": "500014306996",
  "creationTime": "2021-07-15T17:54:12Z",
  "expirationTime": "2021-07-15T18:54:12Z",
  "status": "PROCESSING",
  "action": "NONE"
}

400

Bad Request

application/json

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.

]

Example (from schema)

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

BANK_PROCESSING_FAILED

{
  "error": {
    "code": "DW-BANK-PROCESSING-FAILED",
    "message": "The system is unable to send this request to the processing bank.",
    "details": [
      ""
    ]
  }
}

405

Method Not Allowed

application/json

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.

]

Example (from schema)

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

DW-OPERATION-NOT-ALLOWED

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

Loading...