Add customer payment to wallet

POST

/api/customers/v1/wallet

• Production staging
• Development staging

Adds new payment method to wallet. Either X-CUSTOMER-AUTH header or external_id param is required.

Authorizations

• BasicAuth
• BasicAuth
• customerAuth
• BasicAuth
• onBehalfOf
• BasicAuth
• onBehalfOf
• customerAuth

Parameters

Query Parameters

external_id

string

Customer id in your platform

Request Body

object

callback_url

URL where callback will be sent in case of successful or unsuccessful card confirmation

Required for hosted mode.

string format: url

payment_method

required

Based on your choice in the type field, one of the fields becomes required too.

Required for direct mode.

object

cc_token

Decoded information about tokenized card from card widget.

object

token

required

Card token received from widget or payment response

string

mask

required

Card mask received from widget or payment response

string

expires_at

required

Card expire date received from widget or payment response

string format: date-time

Example

2027-01-02T15:04:05

use_3ds_flow

Flag that indicates necessity of the 3ds confirmation. The 3ds confirmation will be skipped if set false

boolean

encrypted_cc_token

Encoded string containing info returned by card widget.

object

data

required

Encoded string returned by card widget.

string

use_3ds_flow

Flag that indicates necessity of the 3ds confirmation. The 3ds confirmation will be skipped if set false

boolean

type

required

Payment method type

string

Allowed values: cc_token encrypted_cc_token

result_url

URL where user will be redirected from the checkout in case if mode set to hosted

string format: url

make_default

Automatically set new payment method as default in wallet, if it was confirmed.

boolean

mode

required

Describes the way of the integration:

• hosted - returns checkout page, where user can enter his payment details.
• direct - requires payment_method details in request. Usually returns url for second factor (3DS or other).

string

Allowed values: direct hosted express_checkout

fingerprint

object

browser_accept_header

required

string

browser_color_depth

required

string

browser_ip_address

required

string

browser_java_enabled

required

string

browser_language

required

string

browser_screen_height

required

string

browser_screen_width

required

string

browser_time_zone

required

string

browser_time_zone_offset

required

string

browser_user_agent

required

string

Callbacks

WalletAddPaymentConfirmation

POST

$request.body#/callback_url

Returns status of operation after accepting/rejecting on the 3ds page. Callback won’t be sent in case when original request returned success or failure status

Request Body

object

action

Object which contains information about required post-request action. Will be null if action not required.

object

type

value

Action value. Usually it’s a checkout url or 3ds verification url.

string

action_required

Flag that indicates necessity of the post-request action (fill data on the checkout, 3ds confirmation, etc.)

boolean

created_at

string format: date-time

payment_method

object

card

object

expires_at

Card expire date

string format: date-time

mask

Card mask

string

token

Card token

string

full_number

Card number

string

bank_short_name

Bank short name

string

payment_system

Payment system

string

option_id

id of added card. Can be used for payments with wallet payment type.

string format: uuid

is_default

boolean

name

Optional card name set by user.

string

nullable

type

string

Allowed values: card

status

string

Allowed values: init pending success failure

operation

Type of the performed operation

string

Allowed values: add_payment_method

customer

object

external_id

User identifier on your platform

string

Responses

200

Shows that callback was accepted. No further callback after this response.

Responses

200

object

action

Object which contains information about required post-request action. Will be null if action not required.

object

type

value

Action value. Usually it’s a checkout url or 3ds verification url.

string

action_required

Flag that indicates necessity of the post-request action (fill data on the checkout, 3ds confirmation, etc.)

boolean

created_at

string format: date-time

payment_method

object

card

object

expires_at

Card expire date

string format: date-time

mask

Card mask

string

token

Card token

string

full_number

Card number

string

bank_short_name

Bank short name

string

payment_system

Payment system

string

option_id

id of added card. Can be used for payments with wallet payment type.

string format: uuid

is_default

boolean

name

Optional card name set by user.

string

nullable

type

string

Allowed values: card

status

string

Allowed values: init pending success failure

operation

Type of the performed operation

string

Allowed values: add_payment_method

customer

object

external_id

User identifier on your platform

string

400

object

code

string

Allowed values: authorization_failed customer_auth_not_found request_failed internal_error access_not_allowed invalid_request_body payment_settings_not_found transaction_already_paid action_not_allowed action_already_done transaction_success_primary_not_found payment_method_not_allowed wallet_not_configured payment_method_already_confirmed payment_method_not_found invalid_card_token customer_auth_token_expired_or_invalid customer_profile_not_found customer_id_not_passed transaction_not_found waiting_for_verification transaction_amount_limit invalid_data transaction_declined authorization_error transaction_rejected transaction_successful anti_fraud_check card_not_supported confirmation_timeout invalid_card_data invalid_currency pending waiting_for_complete access_error card_expired receiver_info_error transaction_limit_exceeded transaction_not_supported 3ds_not_supported 3ds_required failed_to_create_transaction failed_to_finish_transaction insufficient_funds invalid_phone_number card_has_constraints pin_tries_exceeded session_expired timeout transaction_created waiting_for_redirect wrong_amount test_transaction subscription_successful unsubscribed_successfully wrong_pin wrong_authorization_code wrong_cavv wrong_cvv wrong_account_number confirm_required cvv_is_required confirmation_required sender_info_required missed_payout_method_data card_verification_required incorrect_refund_sum_or_currency payment_card_has_invalid_status wrong_card_number user_not_found failed_to_send_sms wrong_sms_password card_not_found payment_system_not_supported country_not_supported no_discount_found failed_to_load_wallet invalid_verification_code additional_information_is_pending transaction_is_not_recurring confirm_amount_cannot_be_more_than_the_transaction_amount card_bin_not_found currency_rate_not_found invalid_recipient_name daily_card_usage_limit_reached invalid_transaction_amount card_type_is_not_supported store_is_blocked store_is_not_active payment_method_not_found transaction_cannot_be_processed invalid_transaction_status public_key_not_found terminal_not_found fee_not_found failed_to_verify_card invalid_transaction_type restricted_ip invalid_token preauth_not_allowed token_does_not_exist reached_the_limit_of_attempts_for_ip card_branch_is_blocked card_branch_daily_limit_reached completion_limit_reached recurring_transactions_not_allowed transaction_is_canceled_by_payer payment_was_refunded card_is_lost_or_stolen plan_not_found plan_not_active plan_project_missing subscription_auto_renew_locked subscription_not_found subscription_not_active subscription_already_exists order_canceled

message

string

param

string

payment_id

string

type

string

Allowed values: invalid_request_error payment_method_error payment_settings_error payment_error api_error customer_error

error_id

string

429

Too Many Requests.

object

code

string

default: too_many_requests

message

string

default: Too many requests

param

string

payment_id

string

type

string

default: api_error

error_id

string

Headers

X-RateLimit-Limit

integer

Request limit per second.

X-RateLimit-Remaining

integer

The number of requests left for the time window.

X-RateLimit-Reset

integer

Seconds needed for full regeneration.

500

object

code

string

Allowed values: authorization_failed customer_auth_not_found request_failed internal_error access_not_allowed invalid_request_body payment_settings_not_found transaction_already_paid action_not_allowed action_already_done transaction_success_primary_not_found payment_method_not_allowed wallet_not_configured payment_method_already_confirmed payment_method_not_found invalid_card_token customer_auth_token_expired_or_invalid customer_profile_not_found customer_id_not_passed transaction_not_found waiting_for_verification transaction_amount_limit invalid_data transaction_declined authorization_error transaction_rejected transaction_successful anti_fraud_check card_not_supported confirmation_timeout invalid_card_data invalid_currency pending waiting_for_complete access_error card_expired receiver_info_error transaction_limit_exceeded transaction_not_supported 3ds_not_supported 3ds_required failed_to_create_transaction failed_to_finish_transaction insufficient_funds invalid_phone_number card_has_constraints pin_tries_exceeded session_expired timeout transaction_created waiting_for_redirect wrong_amount test_transaction subscription_successful unsubscribed_successfully wrong_pin wrong_authorization_code wrong_cavv wrong_cvv wrong_account_number confirm_required cvv_is_required confirmation_required sender_info_required missed_payout_method_data card_verification_required incorrect_refund_sum_or_currency payment_card_has_invalid_status wrong_card_number user_not_found failed_to_send_sms wrong_sms_password card_not_found payment_system_not_supported country_not_supported no_discount_found failed_to_load_wallet invalid_verification_code additional_information_is_pending transaction_is_not_recurring confirm_amount_cannot_be_more_than_the_transaction_amount card_bin_not_found currency_rate_not_found invalid_recipient_name daily_card_usage_limit_reached invalid_transaction_amount card_type_is_not_supported store_is_blocked store_is_not_active payment_method_not_found transaction_cannot_be_processed invalid_transaction_status public_key_not_found terminal_not_found fee_not_found failed_to_verify_card invalid_transaction_type restricted_ip invalid_token preauth_not_allowed token_does_not_exist reached_the_limit_of_attempts_for_ip card_branch_is_blocked card_branch_daily_limit_reached completion_limit_reached recurring_transactions_not_allowed transaction_is_canceled_by_payer payment_was_refunded card_is_lost_or_stolen plan_not_found plan_not_active plan_project_missing subscription_auto_renew_locked subscription_not_found subscription_not_active subscription_already_exists order_canceled

message

string

param

string

payment_id

string

type

string

Allowed values: invalid_request_error payment_method_error payment_settings_error payment_error api_error customer_error

error_id

string