# Pike Payments API > Pike Payments API enables global payment acceptance and payout processing. Base URL: `https://proxy-demo.pikepayments.com` (demo) / `https://proxy.pikepayments.com` (live). Sign every request body with RSA-SHA256 and send the Base64 signature in the `X-PARTNER-SIGN` header. Include `X-PARTNER-PROJECT` in every request. ## Getting Started - [Documentation](https://developer.pikepayments.com/en): Welcome guide and platform overview for Pike Payments API — payouts, payments, reports Welcome to the guide on how to use Pike Payments' API methods. Our API will help you: - make [payouts](/payouts/payouts-intro) - get [payments](/payments/payment-intro) - get [payout reports](/finance/payouts-daily-report) and [payment reports](/finance/payment-daily-report) :::tip[AI-friendly] We now provide [llms.txt](https://developer.pikepayments.com/llms.txt) and [llms-full.txt](https://developer.pikepayments.com/llms-full.txt) for AI integration. — llms.txt gives a compact overview of the site structure and key sections, allowing AI to quickly understand the context. — llms-full.txt contains a comprehensive plain-text export of all relevant pages, providing deep knowledge of the entire documentation without fetching each HTML page individually. ::: --- - [Quick Start](https://developer.pikepayments.com/en/quick-start): Step-by-step onboarding — application process, test transactions, contract signing, and go-live checklist To start using our API, complete the following steps: ```mermaid flowchart LR id1([Apply on the site]) --> id2([Chat with your manager]) --> id3([Do demo testing]) --> id4([Sign an agreement]) --> id5([Go live]) style id1 fill:#7F82BB; style id2 fill:#7F82BB; style id3 fill:#7F82BB; style id4 fill:#7F82BB; style id5 fill:#7F82BB; ``` 1. Apply on [Pike website](https://pikepay.com). 2. Chat with a Pike manager. - Issue a [private key and a public key](/reference/format#signature) and exchange the public keys. - Provide your Pike manager with the IP address of the host from which requests will be sent. If your IP address changes, please notify the manager in advance to avoid possible connectivity issues. - Inform your Pike manager of your address in the system. This is where the [webhooks](/reference/webhooks) from Pike will be sent (i.e. notifications of events, for example successful payments and payouts). - Get your project identifier. 3. Perform [testing](/reference/testing) (without real data). 4. Sign an agreement with Pike. 5. Exchange data for real operations and check that all the operations come through. - For payouts, top up your balance. - Server for live transactions: **proxy.pikepayments.com** 6. Negotiate your start date and go live. --- - [API Request Format](https://developer.pikepayments.com/en/reference/format): Request/response structure, authentication with RSA-SHA256 signature generation, idempotency key usage, header reference ## API version Currently, two API versions are supported. >Please use the correct names for each version! | API v1 | API v2 | |----------------------|----------------------| | `payments` | **`payout_list`** | | `payment_method` | **`payout_details`** | | `acquiring_payments` | **`payment_list`** | ## Endpoint #### How to generate a request ` + /api/v{API version number} + ` Example: **API v1**: `https://proxy-demo.pikepayments.com/api/v1/session/init/payout` **API v2**: `https://proxy-demo.pikepayments.com/api/v2/session/init/payout` #### Server address - For testing: `https://proxy-demo.pikepayments.com` - For live transactions: `https://proxy.pikepayments.com` ## Request format All the data in requests to Pike and notifications from Pike is transmitted using the HTTP POST method. Message parameters are packed into a JSON object. ## Authentication In the headers of your requests to Pike, always pass the following data for authentication: your project identifier and request signature. | Name | Mandatory | Type | Description | |-------------------------|------------------------------------------------------------------------------------------|--------|---------------------------------------------| | `X-PARTNER-PROJECT` | + | string | Project identifier (from your Pike manager) | | `X-PARTNER-SIGN` | + | string | [Request signature](#signature) | | `X-PARTNER-SUBMERCHANT` | - | string | Payer's identifier (for legal entities) | #### Request example with authentication ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // request body }' ``` ### Request signature The signature is needed to verify the authenticity and integrity of requests. Pike verifies that the requests received are in fact from you (and are complete); you verify Pike's notifications the same way. To create and verify a signature, you will need a private key and a public key. Using your public key, Pike will verify signatures of your incoming requests. #### Generating a key pair You need to generate a pair of keys on your side using the RSA signature algorithm. #### Creating request body signature The signature must be transmitted together with the request to Pike. You need to sign the request body as a whole in the form in which it is sent to Pike's server (after serializing the request body into JSON to send it over HTTP). Use your private key for signing the request. Create a signature using the SHA-256 algorithm. The resulting signature must then be transmitted in the Base64 format. #### Verifying incoming requests from Pike All outgoing requests and webhooks from Pike are signed using Pike's own private key. Using Pike's public key, you need to verify the signatures of the requests and webhooks coming from Pike on your side. The algorithm used is SHA-256. The signature is transmitted in the Base64 format. ### Pike's public keys - [for live transactions](/assets/pike_public_prod.pem) - [for testing](/assets/pike_public_demo.pem) ### Signature generation and validation examples ```openssl showLineNumbers # Generating a private key $ openssl genrsa -out private.pem 2048 # Generating a public key based on the private key $ openssl rsa -in private.pem -pubout > public.pem # Creating myfile.txt file contents $ echo test > myfile.txt # Generating a signature $ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt # Signature ready for transfer $ base64 sha256.sign # Checking the signature $ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt Verified OK ``` ```php showLineNumbers $data = "test"; //Obtaining the pointer to the private and public keys $privateKey = openssl_pkey_get_private("file://private.pem"); $publicKey = openssl_pkey_get_public("file://public.pem"); //Generating a signature based on the data using the private key openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); //Encoding the signature into Base64 to transmit it $base64Signature = base64_encode($signature); //On receiving the signature, decoding it from Base64 $decodedSignature = base64_decode($base64Signature); //Validating the received signature using the public key (success = 1) $isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256); ``` ## Idempotency key An idempotency key is a unique request identifier. You can generate it and use it to ensure that no request with the same unique identifier is attempted more than once. For example, this way you can avoid duplicate payments and payouts. The idempotency key lifetime is 24 hours. ### Format Specify the idempotency key in the request header. | Name | Mandatory | Type | Description | | --------------------------- | ---------- | ------ | -------------------------------------------| | `X-PARTNER-IDEMPOTENCY-KEY` | - | string | Idempotency key (from 4 to 64 characters) | ### Example of a request with an idempotency key ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \ -d '{ // request body }' ``` Methods supporting the idempotency key feature - [`session/create`](/reference/methods#sessioncreate) - [`session/init/payout`](/reference/methods#sessioninitpayout) - [`session/start/payout`](/reference/methods#sessionstartpayout) - [`session/init/payment`](/reference/methods#sessioninitpayment) - [`session/start/payment`](/reference/methods#sessionstartpayment) - [`session/confirm`](/reference/methods#sessionconfirm) - [`session/capture`](/reference/methods#sessioncapture) - [`session/cancel`](/reference/methods#sessioncancel) - [`session/refund`](/reference/methods#sessionrefund) Errors - `idempotency_key_params_mismatch` — The key has already been used for another session - `idempotency_key_already_exists` — The previous request with the same key is still in progress - `idempotency_key_not_supported` — This method cannot be used with an idempotency key ## Payment session All operations in the API take place within a [payment session](/reference/objects#payment_session). A single payment session can combine multiple operations, such as a payment and a refund. --- - [API Testing](https://developer.pikepayments.com/en/reference/testing): Demo environment setup (`proxy-demo.pikepayments.com`), public keys, and test transaction instructions Before performing operations with real money, you need to test everything in the test environment. The [interaction format](/reference/format) and the way you make requests are the same as when working with actual data. The only two things that are different are the server address (`https://proxy-demo.pikepayments.com`) to send requests to and the Pike [public key](/assets/pike_public_demo.pem) to use. ## Data for test operations ### Bank cards > During testing, use at least one 3D Secure card and at least one not protected by 3D Secure. #### With 3D Secure - 2200774546102058 - 4000000000000002 - 5500000000000004 >To go successfully through 3D Secure, specify `12345`. >To fail the procedure, specify any other value. #### Without 3D Secure - 4242424242424242 - 5101180000000007 ### Wallets Any value. ### Bank accounts Any value. ## Testing unsuccessful operations By default, all operations are successful. To test an unsuccessful scenario, specify one of the below values in the `customer.reference` field of the `customer` object. | Value | Result | |---------|------------------------------------------------------------------------------------------------------------------| | `thief` | For payments only. The payment will be cancelled when the money is put on hold | | `loser` | For payments and payouts. The payment will be cancelled when the funds on hold are debited; the payout will fail | --- ## Payouts - [About Payouts](https://developer.pikepayments.com/en/payouts/payouts-intro): Payout methods overview — bank cards (Visa/Mastercard), card data collected via widget, tokenized cards Our API allows for convenient and secure payouts. You can send payouts to any **individuals** to [Visa and Mastercard cards](/payouts/payout-pcidss). > Payouts made to cards cannot be refunded. ### How to obtain card details for payouts If necessary, you can collect bank card details for payouts on your side (you must comply with the additional PCI DSS requirements). Otherwise, you can use our widget: the recipient enters their card details in the widget and you will receive a token which you can then use to perform payouts to this card. >[How to perform a payout to a card](/payouts/payout-pcidss) You can use our [widget](/widget/tokenize-widget) to get tokenized bank card data. >[How to perform a payout to a card using our widget](/payouts/payout-widget) If you already have - a hashed card number obtained via our widget - [a token for recurring payments](/payments/payment-recurring#token) - a tokenized card number obtained via the [`tokenize/elements`](/reference/methods#tokenizeelements) method proceed with the payout using the token. >[How to make a payout to a card using a token](/payouts/payout-tokenized-card) ### Card identifier A card identifier is generated based on the card number and its expiration date if it is available. It allows determining which card the user is using and whether users' cards overlap (if multiple users are using the same card). Its value is passed in the `card_id` parameter. By default, the `card_id` parameter is unique for each project but you can choose this value to be the same across all your projects. [Learn more about the project](/quick-start) :::info[] A card identifier cannot be used to make payments or to retrieve all cards linked to a recipient. ::: ### How to make a payout All API operations are carried out within a [payment session](/reference/objects#payment_session). To create a payout, complete the following steps: 1. Create a payment session sending a [`session/create`](/reference/methods#sessioncreate) request. >Alternatively, you can use the [`session/init/payout`](/reference/methods#sessioninitpayout) method. In this case, specify all the payout parameters right away and skip the next step. 2. Send a [`session/start/payout`](/reference/methods#sessionstartpayout) request to start the payout. 3. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. When you receive it, it means that Pike is ready to make the payout and is waiting for your confirmation. 4. Send a [`session/confirm`](/reference/methods#sessionconfirm) request or a [`session/cancel`](/reference/methods#sessioncancel) request to confirm or cancel the operation. 5. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the result of the payout. If the status is `succeeded`, the payout was successful. Learn more about the [payout statuses](/reference/objects#payout-statuses). ### Sequence diagram ![SequencePCIDSS](/img/docs/payouts/payout_scenario_en.png) ```plantuml @startuml Payout autonumber header Payout participant Partner participant Pike as pike Partner -> pike: sends ""session/create"" pike -> pike: creates a session pike --> Partner: sends 200 OK Partner -> pike: sends ""session/start/payout"" pike -> pike: starts the payout pike --> Partner: sends 200 OK pike -> Partner: sends ""ready_to_confirm"" webhook Partner --> pike: sends 200 OK Partner -> Partner: checks the details Partner -> pike: sends ""session/confirm"" pike --> Partner: sends 200 OK pike ->pike: performs the payout pike -> Partner: sends ""payment_finished"" Partner --> pike: sends 200 OK @enduml ``` --- - [Payout to a Card (PCI DSS)](https://developer.pikepayments.com/en/payouts/payout-pcidss): Send payouts directly to bank cards with full PCI DSS compliance requirements This scenario describes how to perform a payout to a bank card if you decided to obtain and store bank card details on your side (you must comply with the additional PCI DSS requirements). In this case, you have two options: - create a payment session and perform the payout with a single request - create a payment session first, and then perform the payout Below is a description of the option that involves creating a session separately. ## Payout to a card, with a session created separately ### Step 1. Create a payment session Create a session using the [`session/create`](/reference/methods#sessioncreate) method. You will receive the payment session identifier in response. [Learn more about payment sessions](/reference/methods#sessioncreate) Use the request headers to pass your project identifier and the request's signature. [Learn more about the request format](/reference/format) Example of a session creation request ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }' ``` ### Step 2. Start the payout Start the payout using the [`session/start/payout`](/reference/methods#sessionstartpayout) method. - In the `session_id` parameter, pass the identifier of the session created in Step 1. - In the `type` parameter of the `payment_method`/`payout_details` object, pass `card`. - In the [`bank_card`](/reference/objects#bankcard) object, pass the recipient's bank card details. Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } }, "metadata": "good" }' ``` ### Step 3. Wait for a notification that Pike is ready to perform the payout Pike will send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. This means that the payout can be performed and Pike is waiting for you to confirm (or cancel). The webhook body will contain all the details of the payout. Reply with the 200 HTTP code. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", "payments": [{ "id": "po_1234", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` ### Step 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout (using the [`session/confirm`](/reference/methods#sessionconfirm) request) or cancel it (using the [`session/cancel`](/reference/methods#sessioncancel)). Examples ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### Step 5. Wait to be notified of the results of the payout Pike will send you a [`payment_finished`](/reference/webhooks#payment_finished) webhook. The webhook body will contain all the details of the payout. The result of the payout can be found in the `status` field of the `payments`/`payout_list` array. If the status is `succeeded`, then the payout was successful. [Learn more about the payout statuses](/reference/objects#payout-statuses) --- - [Payout to a Card via Widget](https://developer.pikepayments.com/en/payouts/payout-widget): Send payouts using the card widget with reduced PCI DSS scope This scenario describes how to perform a payout to a bank card if you cannot obtain and store the bank card details on your side. You can obtain tokenized card details using the [tokenization widget](/widget/tokenize-widget), and then perform the payout securely. ## Step 1. Generate a public token The token is needed to work with the widget. Send a request to create a [`token`](/reference/methods#token), and use it to pass the type of widget you want to work with. You will receive the token in response. Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tokenize_widget": { "access": true } }' ``` ## Step 2. Show the details collection form to the recipient To do this, you'll need to access our JavaScript library and add the tokenization widget to the page, where the recipient will then be able to fill in the form with their card details. The recipient then enters their card details, and you'll receive tokenized details that you can use to perform the payout. You can initialize the widget using the token you have obtained at the previous step. [How to add the tokenization widget](/widget/tokenize-widget) ## Step 3. Begin the payout 1. Send a request for payment session creation [`session/create`](/reference/methods#sessioncreate). Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }' ``` 2. Send a request for payout creation [`session/start/payout`](/reference/methods#sessionstartpayout). In the `number_hash` field of the [`encrypted_card`](/reference/objects#encrypted_card) object, pass the card number hash (`cardToken.token`) obtained from the widget. In the `participant_details.recipient` object, pass the recipient's name in `full_name`. > You can find information about the token or card through the [`token/info`](/reference/methods#tokeninfo) method. This includes receiving the last 4 digits of the card, in order to show the user the payout destination. The exact set of mandatory parameters depends on the recipient's card type. Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } }, "metadata": "good" }' ``` ## Step 4. Wait for a notification that Pike is ready to perform the payout Pike will send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. This means that the payout can be performed and Pike is waiting for you to confirm (or cancel). The webhook body will contain all the details of the payout. You then reply with the 200 HTTP code. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", "payments": [{ "id": "po_1234", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` ## Step 5. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout (using the [`session/confirm`](/reference/methods#sessionconfirm) request) or cancel it (using the [`session/cancel`](/reference/methods#sessioncancel) request). Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ## Step 6. Wait to be notified of the results of the payout Pike will send you a [`payment_finished`](/reference/webhooks#payment_finished) webhook. The webhook body will contain all the details of the payout. The payout result is in the `status` field of the `payments`/`payout_list` array. If the status is `succeeded`, then the payout has been successful. [Learn more about payout statuses](/reference/objects#payout-statuses) --- - [Payout to a Tokenized Card](https://developer.pikepayments.com/en/payouts/payout-tokenized-card): Send payouts using a card number hash from the tokenization widget, a tokenized card, or a recurring token You can use this method if: - You already have a card number hash obtained via [our widget](/widget/tokenize-widget). - You accept [recurring payments](/payments/payment-recurring). In this case, you can use tokens for recurring payouts. - You decided not to store the bank card details that demand compliance with the additional PCI DSS requirements and got a tokenized card number using the [`tokenize/elements`](/reference/methods#tokenizeelements) method. To start using this method, contact your manager in Pike. > You can use tokens for payouts regardless of the project (`X-PARTNER-PROJECT` in the request header) within which you got them. ### Step 1. Generate a token If you decided not to store bank card details on your side, use the [`tokenize/elements`](/reference/methods#tokenizeelements) method to get a tokenized card number to further use it for payouts. >If you already have a token, skip this step. ### Step 2. Create a payment session Send a [`session/create`](/reference/methods#sessioncreate) request. Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z" } } ``` ### Step 3. Start the payout Send a [`session/start/payout`](/reference/methods#sessionstartpayout) request. In the request, specify: * the session identifier received at the previous step in the request * one of the parameters depending on what data you have: * token—in the [`tokenized_card`](/reference/objects#tokenized_card) object * hash—in the [`encrypted_card`](/reference/objects#encrypted_card) object * token for recurring payouts—in the [`recurrent`](/reference/objects#recurrent) object >To get token details and the last 4 digits of the tokenized card, use the [`token/info`](/reference/methods#tokeninfo) method. Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } }, "metadata": "good" }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "po_1234", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "po_1234", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "po_1234", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` ### Step 4. Wait for a notification that Pike is ready to perform the payout Pike will send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook (using the webhook address you provided to your Pike manager previously). This means that the payout can be performed and Pike is waiting for you to confirm (or cancel) the operation. The webhook body will contain all the details of the payout. Reply with the 200 HTTP code. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", "payments": [{ "id": "po_1234", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` ### Step 5. Confirm or cancel the payout Check the payout details and either confirm it (using [`session/confirm`](/reference/methods#sessionconfirm)), or cancel it (using [`session/cancel`](/reference/methods#sessioncancel)). Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### Step 6. Wait for the results Pike will send you a [`payment_finished`](/reference/webhooks#payment_finished) webhook. The webhook body will contain all the payout details. The payout result is in the `status` field of the `payments`/`payout_list` array. [Learn more about the payout statuses](/reference/objects#payout-statuses) --- ## Payments - [About Payments](https://developer.pikepayments.com/en/payments/payment-intro): Payment methods overview — bank cards, payment form, delayed capture, recurring payments, refunds Below is information you need to know before you start accepting payments. ## Countries and currency You can accept payments in **USD** from any country except those mentioned in the list below. Minimum transaction amount: **$10** Maximum transaction amount: **$1,000** Countries/regions you cannot accept payments from - Afghanistan - Belarus - Canada - Central African Republic - Crimea, Donetsk, Luhansk (Ukraine) - Cuba - DR Congo - Iran - North Korea - Mali - Myanmar - Sudan (North) - Syria - UK - US - Venezuela - Yemen - Zimbabwe [Parameters you need to pass when accepting a payment](/payments/params) ### Types of cards accepted globally - **Mastercard** - **Visa** ### What operations you can perform :::info[] For any payment types other than one-time payments, please check availability with your manager. ::: - [one-time payments by card](/payments/payment-cards) - [delayed capture payments](/payments/payment-hold) (the amount is held for up to 3 days 23 hours, and is then debited either in full or partially) - [recurring payments](/payments/payment-recurring) - [refunds](/payments/payment-refund) (full or partial) ### How to obtain card details securely You can [pass card details with open parameters](/payments/payment-cards) or [use the payment form widget](/payments/payment-with-form). ### Card identifier > To enable this functionality, please contact your manager at Pike. If you do not store bank card details on your side and you need to understand which card the user is using and whether users' cards overlap, you can use the card identifier feature. > If you have multiple projects ([`X-PARTNER-PROJECT`](/reference/format#authentication)), a card identifier may be the same or different for each project. Please inform your manager at Pike which option you prefer. A card identifier is unique and is generated based on the *card number* and its *expiration date*. Its value is passed in the [`card_id`](/reference/objects#card) parameter. This parameter can be passed during payments, recurring payments, and refunds. > A card identifier cannot be used for making payments or for getting all linked cards. A card identifier is not a replacement for a token—you will receive both. ### Tariffs and limits The tariffs for acquiring are specified in your agreement with Pike. You can discuss them with your manager. --- - [Payment Parameters](https://developer.pikepayments.com/en/payments/params): Required parameters for payments from supported countries When you accept a payment from [these countries](/payments/payment-intro#countries), make sure you pass all the required parameters. :::info[] Currently, only [one-time payments](/payments/payment-cards) are available. ::: ## Payments through our widget If you use our payment widget, when you [create a session](/payments/payment-with-form), make sure you pass the following parameters with sender information: - `full_name` - `first_name` - `last_name` - `city` - `street` - `ipv4` - `postal_code` (up to 6 digits) - `email` :::info[] If you do not pass these parameters, we will generate them on our own (except for the first and last names), but the conversion rate might be worse. ::: #### Example of a session/create request ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "sender": { "full_name": "Helen Adams", "first_name": "Helen", "last_name": "Adams", "city": "Miesenbach", "street": "Templstrasse 8", "ipv4": "112.34.152.137", "postal_code": "93401", "email": "helen.adams@hotmail.com" } } }' ``` ## Payments without our widget When you make a payment, make sure you pass the following parameters with sender information: - `full_name` - `first_name`—mandatory - `last_name`—mandatory - `city` - `street` - `ipv4`—mandatory - `postal_code` (up to 6 digits) - `email` You can pass these parameters within any of the methods: - `session/create` - `session/start/payment` - `session/init/payment` :::info[] If you do not pass these parameters, we will generate them on our own (except for the first and last names), but the conversion rate might be worse. ::: #### Example of a session/create request ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "sender": { "full_name": "Helen Adams", "first_name": "Helen", "last_name": "Adams", "city": "Miesenbach", "street": "Templstrasse 8", "ipv4": "112.34.152.137", "postal_code": "93401", "email": "helen.adams@hotmail.com" } } }' ``` --- - [Payments by Bank Card](https://developer.pikepayments.com/en/payments/payment-cards): Direct card payment integration with 3DS authentication >If you have decided not to collect or store bank card data on your side, [accept payments through our payment form](/payments/payment-with-form). You can accept payments by Visa and/or Mastercard cards. ### Card payment scenario >This scenario does not include the payment capture step. [How to make a delayed capture payment](/payments/payment-hold). 1. Create a payment session that is separate from the actual payment ([`session/create`](/reference/methods#sessioncreate)) or a single combined session ([`session/init/payment`](/reference/methods#sessioninitpayment)). At this point, you can tokenize the bank card to [accept payments without the widget](#tokenize_no_widget). 2. If you have created the session separately from the start of the payment, then send a [`session/start/payment`](/reference/methods#sessionstartpayment) request. 3. Pike will send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook, which means that Pike is ready to make the payment and is waiting for your confirmation. 4. Confirm ([`session/confirm`](/reference/methods#sessionconfirm)) or cancel ([`session/cancel`](/reference/methods#sessioncancel)) the payment. 5. Pike will send you an [`action_required`](/reference/webhooks#action_required) webhook in case additional actions are required for the payment, e. g. 3D Secure verification. Redirect the user to the address for 3D Secure. 6. Pike will send you a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. #### Card payment diagram ![Card payment diagram](/img/docs/payments/schema_payment_no_hold_en.png) ```plantuml @startuml CardPayment autonumber header Card payment participant Partner as Partner participant Pike as pike ... Creates payment session and initiates payment ... pike -> Partner: ""ready_to_confirm"" webhook Partner --> pike: 200 OK Partner -> Partner: verifies the order Partner -> pike: ""session/confirm"" method pike --> Partner: 200 OK alt #faf1d7 3DS verification required pike -> pike: passes 3DS end alt pike -> pike: holds funds pike -> pike: debits funds pike -> Partner: ""payment_finished"" webhook Partner --> pike: 200 OK @enduml ``` ### Tokenize card without widget Pike can store tokenized card data on its side. This may be convenient in case you decided not to store the bank card details that demand compliance with the additional PCI DSS requirements, or if you decide not to use the tokenization widget for some reason. You can pass tokenized data to Pike after the first payout transaction and use it for further payouts. You can also reuse the card data received during a payment transaction to make payouts to the same card later. This works both for hashed acquiring data and tokens. To tokenize card data without the widget, use the [`tokenize/elements`](/reference/methods#tokenizeelements) method. Use the token returned by the method in further payment or payout requests. >All data tokenized in this way is not project dependent (e.g., a payout project token can be used to accept payments in another project, etc.) --- - [Payments via Payment Form](https://developer.pikepayments.com/en/payments/payment-with-form): Hosted payment form widget for PCI DSS scope reduction This scenario describes how to accept a bank card payment through the payment form. You should consider this option if you decided not to collect bank card details and not to store them on your side. You can obtain tokenized card details using the [payment form widget](/widget/payment-widget) and then perform the payment securely. >This scenario does not include the payment capture step. [How to make a delayed capture payment](/payments/payment-hold). 1. Create a session using the [`session/create`](/reference/methods#sessioncreate) request. Pass your project identifier and signature in the request headers. [More about the request format](/reference/format) Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }' ``` 2. Send a [`token`](/reference/methods#token) request specifying the session identifier and the type of the widget you are going to call. You will receive a token in response. > If you want to add the **I agree to recurring payments** checkbox to the payment form, specify `true` in the `show_recurrent_checkbox` field. It is required if you want to perform [recurring debiting](/payments/payment-recurring). Note that initially this checkbox can be either empty (by default) or preselected. If you prefer it to be preselected, please contact your Account Manager. Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_123456" } }' ``` 3. Show the payment form to the payer. To do this, you need to access our JavaScript library and add the payment form widget. [How to add the payment form](/widget/payment-widget) 4. Pike will send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. This means that the payment can be performed and Pike is waiting for you to confirm (or cancel) it. The webhook body will contain all the data needed for the payment. Reply with the 200 HTTP code. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` 5. Check the payment details and confirm that you are ready to perform the payment (using the [`session/confirm`](/reference/methods#sessionconfirm) request) or cancel it (using the [`session/cancel`](/reference/methods#sessioncancel) request). >If you receive an `action_required` webhook, send the HTTP 200 OK in response—the user will be redirected for 3D Secure within the widget. Examples ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook. The webhook body will contain all the details of the payment. The result of the payment can be found in the `status` field of the `acquiring_payments/payment_list` array. If the status is `succeeded`, then the payment was successful. [More about the payment statuses](/reference/objects#payment_status) #### Diagram for payment via payment form ![Diagram for payment via payment form](/img/docs/payments/schema_payment_with_form_en.png) ```plantuml @startuml PaymentWithForm autonumber header Payment using the widget participant Partner as Partner participant Pike as pike participant Pike_Widget as Widget participant ACS as ACS Partner -> pike: creates session ""session/create"" pike --> Partner: 200 OK Partner -> pike: issues a public token pike --> Partner: 200 OK Partner -> Widget: calls widget.js ... Customer interaction with the payment form ... Widget -> pike: initializes payment pike -> Partner: ""ready_to_confirm"" webhook Partner --> pike: 200 OK Partner -> pike: ""session/confirm"" method pike --> Partner: 200 OK pike -> pike: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure pike -> Widget: data for passing 3D Secure Widget -> ACS: redirects the user to pass 3D Secure ACS -> pike: passes 3D Secure result end alt pike -> pike: holds funds pike -> Partner: ""ready_to_capture"" webhook Partner --> pike: 200 OK Partner -> pike: confirms ""session/capture"" pike --> Partner: 200 OK pike -> pike: debits funds pike -> Partner: ""payment_finished"" webhook Partner --> pike: 200 OK pike -> Widget: passes payment information Widget -> Widget: displays payment status @enduml ``` --- - [Delayed Capture Payments](https://developer.pikepayments.com/en/payments/payment-hold): Two-stage payments — hold funds on card, then capture fully or partially ## Delayed capture payments You can place a hold on the payment: first authorize or hold the amount of payment on the user’s card and then capture it with a separate request. There is time between the funds being put on hold and the funds being debited so you can send the order to the customer. All in all, all payments made with bank cards consist of two key phases: authorization (when Pike verifies if the needed amount is actually available and places a hold for this amount on the bank card, essentially blocking it) and capture (when Pike clears the payment and writes off the blocked or authorized amount from the bank card balance). There is almost no time gap between the two phases for the standard card payment flow, it looks immediate to the user. However, if you decide to use the delayed capture payment flow, you can decide on the timing when to capture the blocked funds. In this case Pike will not capture the amount immediately, but will do so on your request. **How to enable delayed capture** Pike manages the delayed capture feature. All your payments may have immediate or delayed capture. If captured immediately, the amount of payment will be cleared automatically right after the authorization. If you would like to perform delayed capture payments, please contact your Pike manager. **Hold period** The money is held for **3 days 23 hours**. If you do not debit or unblock it before the end of this period, the money will get unblocked automatically. If you need the money to be debited rather than unblocked after the hold period end, please contact your Pike manager. ### Later capture payment scenario To create a delayed capture payment, complete the following steps: 1. Create a payment session that is separate from the actual payment ([`session/create`](/reference/methods#sessioncreate)) or a single combined session ([`session/init/payment`](/reference/methods#sessioninitpayment)). 1. If you have created the session separately from the start of the payment, then send a [`session/start/payment`](/reference/methods#sessionstartpayment) request. 1. Pike will then send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook, which means that Pike is ready to perform the payment and is waiting for your confirmation. 1. Confirm ([`session/confirm`](/reference/methods#sessionconfirm)) or cancel ([`session/cancel`](/reference/methods#sessioncancel)). 1. If you get an [`action_required`](/reference/webhooks#action_required) webhook from Pike, this means that you will need to take additional action to perform the payment. For instance, the user might need to go through 3D Secure. Redirect the user to the address for 3D Secure. 1. Wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook from Pike. It means the required amount is held on the bank card successfully. It can be captured immediately or later. You can capture the full amount or a portion of it—see [`amount_details`](/reference/objects#amount_details). 1. Capture the full amount that is on hold, a portion of the amount ([`session/capture`](/reference/methods#sessioncapture)), or decline the payment ([`session/cancel`](/reference/methods#sessioncancel)). 1. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. #### Diagram of a delayed capture payments ![Payment diagram with holding](/img/docs/payments/schema_payment_hold_en.png) ```plantuml @startuml PaymentHold autonumber header Delayed capture payments participant Partner as Partner participant Pike as pike participant ACS as ACS Partner -> pike: creates session ""session/create"" pike --> Partner: 200 OK Partner -> pike: initializes payment ""session/start/payment"" pike --> Partner: 200 OK pike -> Partner: ""ready_to_confirm"" webhook Partner --> pike: 200 OK Partner -> pike: ""session/confirm"" method pike --> Partner: 200 OK pike -> pike: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure pike -> Partner: ""action_required"" webhook Partner --> pike: 200 OK Partner -> ACS: redirects the user to pass 3D secure ACS -> pike: 3D Secure result end alt pike -> pike: holds funds pike -> Partner: ""ready_to_capture"" webhook Partner --> pike: 200 OK Partner -> pike: confirms ""session/capture"" pike --> Partner: 200 OK pike -> pike: debits funds pike -> Partner: ""payment_finished"" webhook Partner --> pike: 200 OK @enduml ``` 1. Complete [Steps 1–5](/payments/payment-with-form). > If you receive an `action_required` webhook, send the HTTP 200 OK in response—the user will be redirected for 3D Secure within the widget. 1. Wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook from Pike. It means the required amount is held on the bank card successfully. It can be captured immediately or later. You can capture the full amount or a portion of it—see [`amount_details`](/reference/objects#amount_details). 1. Capture the full amount that is on hold, a portion of the amount ([`session/capture`](/reference/methods#sessioncapture)), or decline the payment ([`session/cancel`](/reference/methods#sessioncancel)). 1. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. #### Diagram of a delayed capture payments ![Payment diagram with holding](/img/docs/payments/schema_payment_with_form_en.png) ```plantuml @startuml PaymentWithForm autonumber header Payment using the widget participant Partner as Partner participant Pike as pike participant Pike_Widget as Widget participant ACS as ACS Partner -> pike: creates session ""session/create"" pike --> Partner: 200 OK Partner -> pike: issues a public token pike --> Partner: 200 OK Partner -> Widget: calls widget.js ... Customer interaction with the payment form ... Widget -> pike: initializes payment pike -> Partner: ""ready_to_confirm"" webhook Partner --> pike: 200 OK Partner -> pike: ""session/confirm"" method pike --> Partner: 200 OK pike -> pike: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure pike -> Widget: data for passing 3D Secure Widget -> ACS: redirects the user to pass 3D Secure ACS -> pike: passes 3D Secure result end alt pike -> pike: holds funds pike -> Partner: ""ready_to_capture"" webhook Partner --> pike: 200 OK Partner -> pike: confirms ""session/capture"" pike --> Partner: 200 OK pike -> pike: debits funds pike -> Partner: ""payment_finished"" webhook Partner --> pike: 200 OK pike -> Widget: passes payment information Widget -> Widget: displays payment status @enduml ``` --- - [Recurring Payments](https://developer.pikepayments.com/en/payments/payment-recurring): MIT/CIT recurring payment flows with token lifecycle management A recurring payment (or repeated payment) enables you to accept a payment and debit money in the following ways: - With a token, without involving the user, those recurring payments are called **Merchant Initiated Transaction** (MIT). - Requesting 3D Secure verification from the user, those recurring payments are called **Customer Initiated Transaction** ([CIT](#recurring-cit)). Currently, recurring payments can only be accepted from a bank card; other options will be added soon. ## Recurring MIT payments **Basic steps** 1. [Obtain the user's consent](#agreement) to recurring payments. 2. [Perform a successful payment](#first_payment) that will recur, and get a [token](#token). 3. [Perform payments using this token](#recurring_payment). ### User consent Recurring payments are pre-authorized by a user and can be made without any future confirmation from them. The user only sees funds debited from their card. This is why you assume full responsibility for such payments: their amount, frequency, and user's consent to them. You need user's consent for dispute situations (e.g. if the user complains about an unauthorized debit). **How to obtain user's consent** You can do it in any way you find convenient. The main point is that you need to verify the user had been aware of automatic debits when they made the first payment, and agreed to them. How to do it: 1. Describe the payment terms to make sure the user will read them. 2. Ask the user to confirm they understand and agree to the terms (e.g. add an unambiguous checkbox like **Save card**, **Enable automatic payments**, **Enable recurring donations**, etc.). If the user ticks the checkbox, thus verifying their consent, recurring payments become enabled. If they don't, recurring payments are not activated. The checkbox can be on your side (in this case, you will decide how it looks and where it is located) or on our side—in our [payment widget](#first_payment). ### Token for recurring payments You need to perform one payment successfully, selecting the option to save bank card details. In response to this payment, you will receive a [token](/reference/objects#recurrent_token_info). This token can be saved and used to accept future payments. **How to get a token** - When creating a payment session. Send `recurrent=true` (in the [`payment_options`](/reference/objects#payment_options) object). You can do this when [creating a payment session](/reference/methods#sessioncreate) or in any payment request. If such a payment is successfully performed, you will receive a token for recurring payments with which you will be able to repeat the payment. > In this case, you need to get the user's consent on your side beforehand. - In our payment widget. If you perform a payment with the widget, you can show the **I agree to recurring payments** checkbox to the user. If the user ticks this checkbox and the payment is performed successfully, you will receive the token for recurring payments. **Token statuses** When you create a token, it becomes active (`is_active: true`) and you can perform payments with the token. If a token is inactive (`is_active: false`), the payment will not be processed and you will see an error. To learn the token status send a [`token/info`](/reference/methods#tokeninfo) request. In the `type` parameter, pass `recurrent_token`, in the `recurrent_token.token` parameter, pass the token. In return, you will get [`info`](/reference/objects#info_recurrent) with the date of token expiration (`finished_at`) and status (`is_active`). The token expiration setting (`finished_at`) isn't processed by Pike, i.e. the token will remain active even after the specified expiration date. If `is_active: true`, you can perform payments with this token. Please note that an active token won't guarantee a successful payment, since the payment can be, for some reason, rejected by the card issuer. **How to disable a token** If you don't want to use a token for payments anymore (e.g. a user disabled recurring payments), send a [`recurrent/disable`](/reference/methods#recurrentdisable) request. In response, you will receive [`recurrent`](/reference/objects#recurrent_token_info). If `is_active: false`, it means the token is disabled and you cannot perform payments with the token anymore. > After the token is disabled, the token expiration setting (`finished_at`) may contain a date of the year 2000. This value won't affect anything, so please disregard it. ### How to make a recurring MIT payment #### Step 1. Successfully perform a payment with an instruction to create a token >[How to make a payment without our widget](/payments/payment-cards) When creating a payment session or sending a payment request, pass `true` in the `recurrent` parameter of the [`payment_options`](/reference/objects#payment_options) object. Example of a payment request with an instruction to create a token ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "30", "security_code": "087" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "recurrent": true } }' ``` >[How to make a payment with our widget](/payments/payment-with-form) If you perform a payment with our widget, you can show the user the **I agree to recurring payments** checkbox. To do this, in the [widget token creation request](/reference/methods#token), pass `true` in the `show_recurrent_checkbox` field. > This is optional. You can obtain the user's consent earlier, pass `recurrent: true` when creating a payment session, and show the user the widget with no checkboxes—the same as for one-time payments. Example of creating a token for the widget with a checkbox to agree to recurring payments ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_34851", // highlight-next-line "show_recurrent_checkbox": true } }' ``` Then, [create a payment form](/widget/payment-widget) with this token. If the user ticks the **I agree to recurring payments** checkbox (i.e. agrees to enable recurring debiting from their card), you will receive a token. #### Step 2. Save the token If the payment is performed successfully (and the user enables recurring debiting when paying through the form), you will get the token in the [`payment_finished`](/reference/webhooks#payment_finished) webhook. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "recurrent": { // highlight-next-line "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 10000, "currency": "usd" }, "payment_options": { "recurrent": true } }] } }' ``` #### Step 3. Accept payments using the token Send a request to accept a payment with the `recurrent` payment type. Instead of a bank card, pass the token you saved after the previously accepted payment. Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" } }' ``` ## Recurring CIT payments Recurring CIT (**Customer Initiated Transaction**) payments allow you to make payments using a token with payer verification via 3DS. To guarantee successful CIT payments, we recommend using the [project identifier](/reference/format#authentication) intended for 3DS payments. ### How to make a recurring CIT payment 1. Initiate a payment session using the [`session/init/payment`](/reference/methods#sessioninitpayment) method. In the request, provide the [`payment_details.recurrent.initiator:client`](/reference/objects#recurrent) value and specify the return URL for the payer after completing 3DS verification in the `return_url` parameter. Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "recurrent", "recurrent": { "token": "token_value", "initiator": "client" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://pikepayments.com" } }' ``` 2. Receive from Pike an [`action_required`](/reference/webhooks#action_required) webhook with the [data for a redirect to the 3DS verification page](/reference/objects#customer_interaction_redirect). Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://proxy.pikepayments.com?foo=bar", "base_url": "https://proxy.pikepayments.com", "method": "GET", "qs": { "foo": "bar" }, "params": { "paReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` 3. Redirect the user to the URL received in the `customer_interaction.redirect.url` field. Pay attention to the redirection method in the `customer_interaction.redirect.method` field: it can be either GET or POST. >Note that after completing 3DS verification, the payer will be redirected to the `return_url`. The `return_url` may be called using either the GET or POST method, and you may need to configure a conversion (redirect) from a POST request to a GET request. 4. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook with the result of the recurring payment. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "recurrent": { "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 10000, "currency": "usd" } }] } }' ``` #### Recurring CIT payment diagram ![](/img/docs/payments/cit_en.png) ```plantuml @startuml actor Sender as actor participant Partner as mer participant Pike as pike participant ACS as acs autonumber actor -> mer: Requests a recurring payment mer -> mer: Customer validation required mer -> pike: ""/api/v1/session/init/payment:"" \n - "" "recurrent": {"" \n \t "" "token": "token_value","" \n \t "" "initiator": "client"},"" \n \t ... \n - ""return_url"" (for return from ACS) \n - other required settings mer mer: ""action_required"" note left 3DS data end note pike actor: redirected at ACS actor -> acs: enters code acs --> actor: redirects the Customer using ""return_url"" note right #FFAAAA For ""return_url"", the method can be GET or POST end note pike -> mer: ""payment_finished"" @enduml ``` --- - [Refunds](https://developer.pikepayments.com/en/payments/payment-refund): Full and partial refund flows You can return a successful payment to the sender as follows: - Within the **refund** operation – this is the most commonly encountered situation, the payment can be returned completely or partially. - Within the **chargeback** procedure – this procedure cannot be initiated by the client, a notification about it is sent by Pike. In this case, the amount is withdrawn from the compensation. In both cases, a record will appear in the [report](/finance/payment-daily-report). ### How to perform a refund #### Step 1. Send a refund request >Please note that you can only send a request for a **refund**, not a **chargeback**. To perform a refund, send a [`session/refund`](/reference/methods#sessionrefund) request. In the `session_id` field, pass the identifier of the [payment session](/reference/objects#payment_session) for the payment you need to refund. In `amount_details.amount`, specify the amount of the refund. If you leave this blank, the money will be refunded in full (i.e. for the full amount of the payment in question). Example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230" }' ``` #### Step 2. Wait to be notified of the results of the refund After the refund has been issued, Pike will send you a [`payment_refunded`](/reference/webhooks#payment_refunded) webhook with the results. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 1000, "currency": "usd" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 1000, "currency": "usd" } }], "transaction_info": { "rrn": "425307614918" } }] } }' ``` --- ## Widgets - [Payment Form Widget](https://developer.pikepayments.com/en/widget/payment-widget): Payment widget technical integration guide with customization options You can use the payment form widget to perform payments. You add the widget to the page, show it to the user, and the user then interacts with the widget. [How to perform a payment through the payment form](/payments/payment-with-form) ![Widget](/img/docs/widgets/payment_widget_onepayment.png) ![WidgetRec](/img/docs/widgets/payment_widget.png) ![WidgetRec](/img/docs/widgets/payment_widget_noname.png) ```html showLineNumbers Payment form widget document.addEventListener('DOMContentLoaded', function () { if (!window.PikePaymentForm) { return; } const paymentForm = new PikePaymentForm('publicToken', { isCvcMasked: true, hideCardHolderField: false, customerInteractionRedirect: { target: "_blank", }, }); paymentForm.render(); }); ``` ## How to add a widget to a page #### 1. Link the scripts and styles ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2. Add a container with the widget ```html showLineNumbers ``` #### 3. Create an instance of the widget Once the script is linked to the page, the `PikePaymentForm` class will appear in the global scope. To create the payment form, pass the public token obtained to work with the widget to the constructor. ```js showLineNumbers const paymentForm = new PikePaymentForm('public token'); ``` To display the payment form, call the `render()` method: ```js showLineNumbers paymentForm.render(); ``` ## Widget API ### `PikePaymentForm` Payment form class constructor. ```js showLineNumbers const paymentForm = new PikePaymentForm(publicToken[, options]) ``` | Parameter | Type | Description | |---------------------|-------------|---------------------------------------------------------------------------------------------------------------------| | `publicToken` | string | Mandatory. Public token | | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the form will be inserted. Default value: `` | ### Method: `paymentForm.render()` The method displays the form on the page, in the container defined by the `options.container` parameter. ```js showLineNumbers paymentForm.render([options]) ``` | Parameter | Type | Description | |---------------------|-------------|-------------------------------------------------------------------------------------------------------------------------| | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the form will be inserted. Default value:`` | ### Event handler: `paymentForm.onReady` Handles the event of the form becoming ready for work. ```js showLineNumbers paymentForm.onReady = function () { /* handler */ } ``` ### Event handler: `paymentForm.onPaymentStart` Handles the event occurring at the start of the payment process. ```js showLineNumbers paymentForm.onPaymentStart = function () { /* handler */ } ``` ### Event handler: `paymentForm.onPaymentSuccess` Handles the event occurring when the payment process finishes successfully. ```js showLineNumbers paymentForm.onPaymentSuccess = function () { /* handler */ }; ``` ### Event handler: `paymentForm.onPaymentFail` Handles the event occurring when the payment process finishes unsuccessfully. ```js showLineNumbers paymentForm.onPaymentFail = function (error) { /* handler */ } ``` ### Event handler: `paymentForm.onDestroy` Handles the event of the widget getting closed. ```js showLineNumbers paymentForm.onDestroy = () => { /* handler */ } ``` ## Widget customization ### Hide CVV/CVC details You can customize the CVV/CVC field of the widget to make it display only the last digit entered by customers and mask the others entered before with *. To do this, add the `isCvcMasked` flag into the widget constructor, as follows: ```js showLineNumbers const paymentForm = new PikePaymentForm('publicToken', { isCvcMasked: true, }); ``` ### Open the 3D Secure window as required You can choose how to open the 3D Secure window for the user. Use the `target` parameter of the `customerInteractionRedirect` object with the following options: - `_blank`—in a new tab - `_self`—in the same frame - `_parent`—in the next-level frame if the frames are nested in one another - `_top`—outside of all the frames as the top window Default: `_top`. >Note that: >- We do not recommend using the `_self` option for security reasons. >- If you use the `_blank` option, the user will need to allow pop-ups in the browser or follow the redirection link from the payment widget. ### Hide the cardholder name To hide the **Cardholder** field, pass `hideCardHolderField: true`. By default, the field is shown. ### Appearance You can link your own styles after the library ones and override them, like this: ```html showLineNumbers ``` ```css showLineNumbers /* custom-styles.css */ .pike-Field__label { color: green; } ``` > You cannot yet change the appearance of the values entered inside the iframe. This functionality will be added later. Also, you can modify texts of the widget UI elements. Here is what you can change: - labels - placeholders - error messages - prompt texts - button names - footer texts To do that, you should pass the `Options` object with UI elements parameters within the [PikePaymentForm](#pikepaymentform) widget constructor. | Widget UI element | Parameter name | Type | Default value | | ---------------------------------------------------------------------------------- | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------- | | Widget text settings | `texts` | object | | | Failed payment screen | `failedPaymentScreen` | object | | | Failed payment screen heading | `title` | string | `Error` | | Payment form | `paymentForm` | object | | | Payment button name | `buttonPayLabel` | string | `Pay` | | Cardholder name text | `cardholderLabel` | string | `Cardholder` | | Cardholder name prompt text | `cardholderNote` | string | None | | Cardholder name placeholder | `cardholderPlaceholder` | string | `Full name` | | Card number | `cardNumberLabel` | string | `Card number` | | Card number prompt text | `cardNumberNote` | string | None | | Card number placeholder | `cardNumberPlaceholder` | string | `0000 0000 0000 0000` | | CVV/CVC number | `cvvLabel` | string | `CVC` | | CVV/CVC number prompt text | `cvvNote` | string | None | | CVV/CVC number placeholder | `cvvPlaceholder` | string | `CVC` | | Card expiration date | `expireDateLabel` | string | `Expiration date` | | Card expiration date prompt text | `expireDateNote` | string | `As stated on the card` | | Card expiration date placeholder | `expireDatePlaceholder` | string | `MM/YY` | | Recurring payment checkbox | `recurrentLabel` | string | `I agree to recurring payments` | | Terms of agreement | | | | | Terms of agreement. The text within the mandatory `{{#link}}{{/link}}` tags is used as a link to the terms of agreement source. | `termsAgreement` | string | `By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}}` | | Field validation error messages | `validationErrors` | object | | | Invalid card number | `INVALID_CARD_NUMBER` | string | `Invalid card number` | | Invalid CVV/CVC | `INVALID_CVV` | string | `CVV/CVC has 3 digits` | | Invalid card expiration date | `INVALID_EXPIRY_DATE` | string | `Invalid date` | | Required field value is missing | `IS_REQUIRED` | string | `Required field` | | Payment process page | `paymentProcessScreen` | object | | | Payment processing page text | `description` | string | `Just a moment` | | Payment process screen heading | `title` | string | `Payment processing...` | | Redirecting page (3D Secure) | `redirectionScreen` | object | | | Invitation message to proceed with redirection in case of automatic redirection failure. The text within the mandatory `{{#link}}{{/link}}` tags is used as a link. | `followTheLink` | string | `If you haven't been redirected automatically, use {{#link}}this link{{/link}}.` | | Redirecting page heading | `title` | string | `Payment processing...` | | Automatic redirection warning, includes 3 seconds countdown timer. The `{{countdown}}` value is mandatory and will be replaced with the timer.Use the `{{#strong}}{{/strong}}` tags to emphasize the timer in bold. | `waitForRedirectToBanksPage` | string | `You will be redirected to the issuer bank's page in {{#strong}}{{countdown}} seconds.{{/strong}}` | | Successful payment page | `successPaymentScreen` | object | | | Successful payment page header | `title` | string | `Payment success` | | Transaction data | `transactionData` | object | | | Transaction amount label | `amountLabel` | string | `Amount` | | Payment type data (card type and masked card number) label | `creditCardLabel` | string | `Card` | | Transaction ID label | `transactionIdLabel` | string | `Transaction ID` | | Unknown error message | `unknownError` | string | `Something went wrong...` | #### An example of code to modify texts: ```javascript showLineNumbers const paymentForm = new PikePaymentForm('', { isCvcMasked: true, hideCardHolderField: false, texts: { failedPaymentScreen: { title: 'Payment error', }, paymentForm: { buttonPayLabel: 'Pay', cardholderLabel: 'Cardholder', cardholderNote: '', cardholderPlaceholder: 'Full name', cardNumberLabel: 'Card number', cardNumberNote: '', cardNumberPlaceholder: '0000 0000 0000 0000', cvvLabel: 'CVC', cvvNote: '', cvvPlaceholder: 'CVC', expireDateLabel: 'Expiration date', expireDateNote: 'As stated on the card', expireDatePlaceholder: 'MM/YY', recurrentLabel: 'I agree to recurring payments', termsAgreement: 'By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}}', validationErrors: { INVALID_CARD_NUMBER: 'Invalid card number', INVALID_CVV: 'CVV/CVC has 3 digits', INVALID_EXPIRY_DATE: 'Invalid date', IS_REQUIRED: 'Required field', }, }, paymentProcessScreen: { description: 'Just a moment', title: 'Processing payment...', }, redirectionScreen: { followTheLink: 'If you haven`t been redirected automatically, use {{#link}}this link{{/link}}.', title: 'Processing payment...', waitForRedirectToBanksPage: 'You will be redirected to the issuer bank`s page in {{#strong}}{{countdown}} seconds.{{/strong}}', }, successPaymentScreen: { title: 'Payment success', }, transactionData: { amountLabel: 'Amount', creditCardLabel: 'Card', transactionIdLabel: 'Transaction ID', }, unknownError: 'Something went wrong...', }, }); ``` ### End user errors While interacting with our widget, end users may receive the errors stated below. | Error code | Error description | |---------------------------|--------------------------------------------------------------------------| | `3DS_error` | To complete the transaction successfully, 3DS authentication is required | | `activity_count_exceeded` | The activity/amount limit for the card is exceeded | | `bank_card_expired` | The bank card is past its expiration date | | `declined_by_issuer_bank` | The operation was declined by the issuing bank | | `insufficient_funds` | The card does not have enough funds | --- - [Tokenization Widget](https://developer.pikepayments.com/en/widget/tokenize-widget): Card data tokenization widget for secure card data collection This widget allows you to securely perform bank card operations. You connect the widget to the page in your service, display it to the user, and obtain their card details in tokenized form. You can then use these details to perform payouts. Everything is secure: the input form is displayed in a frame, and all the operations are performed using a unique token. > The card number hash can be stored and used for repeat payouts to this card. > You can find information about the token or card through the [`token/info`](/reference/methods#tokeninfo) method. This includes receiving the last 4 digits of the card, in order to show the user the payout destination. [How to make a payout to a card via the widget](/payouts/payout-widget) ![Widget](/img/docs/widgets/payout_widget.png) ```html showLineNumbers Widget for card number tokenization. document.addEventListener('DOMContentLoaded', function () { if (!window.PikeCardTokenizer) { return; } const cardTokenizer = new PikeCardTokenizer('public token'); cardTokenizer.onTokenizationSuccess = function (cardToken) { // Handling the event of successful token reception. }; cardTokenizer.render(); }); ``` ## How to add a widget to a page To use widgets, you will need to connect our JavaScript library to the page and obtain a token (using the [token](/reference/methods#token) method). #### 1. Link the scripts and styles You need to link the widget's script and styles to the page. ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2. Add a container with the widget ```html showLineNumbers ``` #### 3. Create an instance of the widget After linking the script to the page, the `PikeCardTokenizer` class will appear in the global scope. To create the tokenization form, pass the public token created to work with the widget into the constructor. ```js showLineNumbers const cardTokenizer = new PikeCardTokenizer('public token'); ``` Action upon successful reception of the token: ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { // ... }; ``` To display the form, call the `render()` method: ```js showLineNumbers cardTokenizer.render(); ``` ## Widget API ### `PikeCardTokenizer` Tokenization form class constructor. ```js showLineNumbers new PikeCardTokenizer(publicToken[, options]) ``` | Parameter | Type | Description | |-----------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------| | `publicToken` | string | Mandatory. The public token | | `options` | object | Additional settings object | | `options.container` | HTMLElement | The container into which the form will be inserted. The default value is:`` | | `options.texts` | object | | | `options.texts.cardNumberLabel` | string | A label for the card number input field. The default value is: `Card number` | | `options.texts.submitButtonLabel` | string | Tokenization button label. The default value is `Link the card` | ### Method: `cardTokenizer.render()` This method displays the form on the page, in the container defined by the `options.container` parameter. ```js showLineNumbers cardTokenizer.render(); ``` ### Event handler: `cardTokenizer.onReady` Handles the event of the form becoming ready for work. ```js showLineNumbers cardTokenizer.onReady = function () { /* handler */ }; ``` ### Event handler: `cardTokenizer.onTokenizationStart` Handles the event occurring at the start of the tokenization process. ```js showLineNumbers cardTokenizer.onTokenizationStart = function () { /* handler */ }; ``` ### Event handler: `cardTokenizer.onTokenizationSuccess` Handles the event occurring when the tokenization process finishes successfully. ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { /* handler */ }; ``` | Parameter | Type | Description | |-------------------------------------|--------|-------------------------------------------------------------------------------------------| | `cardToken` | object | | | `cardToken.info` | object | Additional card information object | | `cardToken.info.card_network` | string | Payment card network. Possible values: `visa`, `mastercard`, `mir` | | `cardToken.info.card_type` | string | Card type. Additionally specifies the subbrand (`visa_electron`, `maestro`, `mirmaestro`) | | `cardToken.info.masked_card_number` | string | Masked card number value, e.g. `424242******4242` | | `cardToken.token` | string | Card number hash | ### Event handler: `cardTokenizer.onTokenizationFail` Handles the event occurring when the tokenization process finishes unsuccessfully. ```js showLineNumbers cardTokenizer.onTokenizationFail = function (error) { /* handler */ }; ``` ## Widget customization ### Appearance You can link your own styles after the library ones and override them, like this: ```html showLineNumbers ``` ```css showLineNumbers /* custom-styles.css */ .pike-Field__label { color: green; } ``` > You cannot yet change the appearance of the value entered into the form (inside the iframe). This option will be added later. ### Texts You can change the text of the form using the `options.texts` parameter in the [`PikeCardTokenizer`](#pikecardtokenizer) constructor. --- ## Reports - [Payout Daily Report](https://developer.pikepayments.com/en/finance/payouts-daily-report): Daily payout registry in CSV format with delivery options The daily report is sent in CSV format to the email address specified in your agreement with Pike. If you wish to receive the reports in the XLSX or in a different way, for example, via SFTP, please contact your Pike manager. ## How to use the report The report sent by Pike contains a list of all successful operations for a day (24 hours). You need to check the operations on your side against those in the report. In case of any discrepancy, contact your Pike manager. The timeframe for making corrections is specified in your agreement with Pike. ## Report file name `_YYYY-MM-DD_YYYY-MM-DD` ## Report fields | Field name | Format | Description | Example | | ------------------ | ------- | ------------------------- | -------------------- | | operationId | string | Pike payout identifier | `po_2196490` | | transactionDate | string (date in the following format: YYYY-MM-DD HH:MM:SS) | Time of payout creation on Pike's side | `2024-06-21 23:17:55` | | finishedAt | string (date in the following format: YYYY-MM-DD HH:MM:SS) | Time of payout completion on Pike's side | `2024-06-21 23:17:56` | | typeOfPayment | string | Transaction type. Options: `Advice` is a payout; `Refund` is a refund. [More details](/finance/payouts-daily-report#payment_types) | `Advice` | | paymentFast | int | Payout type. `0` is a regular payout, `1` is a fast payout | `0` | | paymentSessionId | string | Payment session identifier | `ps_2525018` | | paymentSessionMerchantMetadata | string | Your additional data that you passed within the request for the operation | `"good"` | | paymentMethodIdentity | string | Payment instrument (masked card number, account number) | `420080******8800` | | product | string | Product or service identifier according to the agreement with Pike | `new_payouts` | | grossLocalAmount | decimal | Total amount of the payout, including the fee | `110` | | paymentLocalAmount | decimal | Payout amount after the fee is deducted | `100` | | feesLocalAmount | decimal | Pike's fee (`grossLocalAmount - paymentLocalAmount`) | `10` | | currency | string | Three-letter currency code (ISO) | `USD` | | receipt | string | Online receipt (optional field) | | | RRN | string | Retrieval Reference Number: the unique identifier of a transaction with Pike (optional field) | `425307614918` | ### Payout types (typeOfPayment) - `Advice` is a successful payout. - `Refund` is a refund of a successful payout. ## How to receive large report files If required, Pike can send report files with one of the methods below: - A CSV or XLSX file split into parts in CSV or XLSX format. - A single ZIP archive file (CSV or XLSX file archived). - A ZIP archive file split into parts (CSV or XLSX file archived and then split into parts). This can help to deal with the issues when your email server cannot process a single email file with a size larger than specified. To know more about this service, please contact your manager at Pike. In some cases, Pike can split and/or archive reports based on their own business and/or operational needs. A report file is split into parts by the number of transactions. --- - [Payment Daily Report](https://developer.pikepayments.com/en/finance/payment-daily-report): Daily payment registry in CSV format with delivery options The daily report is sent in CSV format to the email address specified in your agreement with Pike. If you wish to receive the reports in the XLSX or in a different way, for example, via SFTP, please contact your Pike manager. ## How to use the report The report sent by Pike contains a list of all successful operations for a day (24 hours). You need to check the operations on your side against those in the report. In case of any discrepancy, contact your Pike manager. The timeframe for making corrections is specified in your agreement with Pike. ## Report file name `_YYYY-MM-DD_YYYY-MM-DD` ## Report fields | Field name | Description | Field length |Example | |--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------|----------------------| | ID | Pike payment identifier | 15-32 |`pm_2048` | | paymentSessionId | Payment session identifier | 0-100 |`ps_3230` | | Project name | The name of your project on Pike's side | 2-100 |`acquiring_card` | | Type of payment | Payment type. Possible options: `Adjustment`, `Advice`, `Refund`, `Recurrent`. [More details](/finance/payment-daily-report#payment_types) | 10-16 |`Advice` | | Amount | Total of the operation | 1-12 |`110` | | Settlement | Total of the settlement Pike must transfer to you. The total of the settlement can be negative, for example for `Refund` or `Chargeback` | 1-12 |`-2` | | Fee | Pike's total fee (as per the agreement). Specified as a negative value. | 1-12 |`-2` | | Transaction Date and Time | Date and time of the transaction on Pike's side | 19 |`11.01.2020 00:00:08` | | Card number | Masked number of the card/wallet number used to make the payment | 9-19 |`4...1878` | | RRN | Retrieval Reference Number: the unique identifier of a transaction with Pike (optional field) | 12 |`425307614918` | | paymentSessionMerchantMetadata | Your additional data that you passed within the request for the operation | 6-20 |`1Di732vw57` | ### Payment types (Type of payment) - `Adjustment` – partial cancellation of a transaction - `Advice` – successful transaction - `Refund` – rollback of a successful transaction - `Recurrent` – [recurring payment](/payments/payment-recurring) (automatic payment or repeated payment) ## How to receive large report files If required, Pike can send report files with one of the methods below: - A CSV or XLSX file split into parts in CSV or XLSX format. - A single ZIP archive file (CSV or XLSX file archived). - A ZIP archive file split into parts (CSV or XLSX file archived and then split into parts). This can help to deal with the issues when your email server cannot process a single email file with a size larger than specified. To know more about this service, please contact your manager at Pike. In some cases, Pike can split and/or archive reports based on their own business and/or operational needs. A report file is split into parts by the number of transactions. --- ## API Reference - [Objects](https://developer.pikepayments.com/en/reference/objects): Complete reference of all API objects — payment, payout, customer, session details, amounts, fees ## `acquiring_payments` = `payment_list` >Use `acquiring_payments` for API v1, and `payment_list` for API v2. All the payment details. | Name | Mandatory | Type | Description | |------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `id` | + | string | Unique payment identifier | | `status` | + | string | Payment status. Possible values: `succeeded`, `in_progress`, `pending`, `failed` | | `created_at` | + | string | Creation date in ISO 8601 format | | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | + | object | [Amount](/reference/objects#amount_details) | | `amounts` | - | object | [Transaction fee](/reference/objects#amounts) | | `finished_at` | - | string | Completion date in ISO 8601 format | | `customer` | + | object | [User (payer) details](/reference/objects#customer) | | `recurrent` | - | object | [Details needed to perform recurring payments](/reference/objects#recurrent_token_info) | | `participant_details` | - | object | [Participants' details](/reference/objects#participant_details) | | `refunds` | - | array | [Refund list](/reference/objects#refunds) | | `customer_interaction` | - | object | [Data needed for user interaction](/reference/objects#customer_interaction) | | `transaction_info` | - | object | [Transaction details](/reference/objects#transaction_info) | | `payment_options` | - | object | [Payment parameters](/reference/objects#payment_options) | `metadata` | - | * | [Any additional information](/reference/objects#metadata) | | `error` | - | object | [Error description](/reference/objects#error) | #### Payment statuses (`status`) - `in_progress` — the payment is being processed. - `pending` — awaiting your confirmation ([`session/confirm`](/reference/methods#sessionconfirm)) or cancellation ([`session/cancel`](/reference/methods#sessioncancel)). - `succeeded` — the payment has been completed successfully. - `failed` — the payment has not gone through due to an error. ## `acquiring_widget` Settings for the payment form widget (for performing bank card payments). | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Identifies the payment session for which the payment will be performed | | `show_recurrent_checkbox` | - | bool | Whether to display the **Enable automatic payments** checkbox in the widget interface | | `success_return_url` | - | string | URL to which the user is redirected after a successful payment | | `failure_return_url` | - | string | URL to which the user is redirected when an error occurs during the payment | | `success_on_hold` | - | bool | Whether to show a message about a successful payment to a payer when holding. By default, `false` and the widget shows a loading screen until the end of the hold | | `redirect_target` | - | string | Redirect link open options: - `top` — outside of all the frames as the top window - `self` — in the same frame - `parent` — in the next-level frame if the frames are nested in one another. Default: `top` | ## `amount_details` Amount object. | Name | Mandatory | Type | Description | |------------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount value in minor currency units (cents). For 100 USD, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `usd` | ## `amounts` Transaction fee. | Name | Mandatory | Type | Description | |-------|-----------|--------|---------------------------------------------------| | `fee` | - | object | [Fee details](/reference/objects#fee) | ## `bank_account` The payout recipient's account description. | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------------|--------|-------------------------------------------------------------------------------------------| | `system_type` | + | string | Bank payment system. Options: `ru`, `faster_payment_system`, `faster_payment_system_verification` | | `ru` | - (mandatory for `system_type = ru`) | object | [Recipient's bank account (region: ru)](/reference/objects#ru) | | `faster_payment_system` | - (mandatory for `system_type = faster_payment_system`) | object | [Recipient's data in the Faster Payment System](/reference/objects#faster_payment_system) | | `faster_payment_system_verification` | - (mandatory for `system_type = faster_payment_system_verification`) | object | [Data for the recipient verification in the Faster Payment System](/reference/objects#faster_payment_system_verification) | ## `bank_card` An unencrypted card object. | Name | Mandatory | Type | Description | |--------------------|------------------------------------------|--------|---------------------| | `number` | \+ | string | Card number | | `expiration_month` | \- (mandatory for payments if available) | string | Month | | `expiration_year` | \- (mandatory for payments if available) | string | Year | | `security_code` | \- (mandatory for payments if available) | string | CVC (security code) | | `cardholder_name` | \- | string | Cardholder's name | ## `card` The payout recipient's bank card details. | Name | Mandatory | Type | Description | |------------------|-------------------------------------------|--------|--------------------------------------------------------------------------------------------------| | `type` | + (not returned in responses) | string | Card details transmission type. Possible values: `bank_card`, `encrypted_card`, `tokenized_card` | | `bank_card` | - (mandatory for `type = bank_card`) | object | [Unencrypted card](/reference/objects#bankcard) | | `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Card with encrypted fields (tokenized)](/reference/objects#encrypted_card) | | `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | | `brand` | - | string | Card information. Returned in notifications, needed for user display | | `last4` | - | string | Card information. Returned in notifications, needed for user display | | `bin` | - | string | Bank Identification Number (BIN) (the first 6 digits of a card number) | | `card_id` | - | string | [Card identifier](/payments/payment-intro#cross-identifier-card) | | `country_iso3` | - | string | Country code (ISO 3166-1 alpha-3) | ## `card_elements` The number of a card for tokenizing. | Name | Mandatory | Type | Description | |---------------|-----------|--------|-----------------------------------| | `ref` | + | string | Fixed value, always `number` | | `type` | + | string | Fixed value, always `card_number` | | `card_number` | + | string | Card number | ## `contacts` An array with the contacts of a user (payout recipient or payment sender). | Name | Mandatory | Type | Description | |---------|-----------|--------|---------------------| | `email` | - | string | User's email | | `phone` | - | string | User's phone number | ## `customer` Data about the user (payout recipient or payment sender) in your system. E.g. the login that lets you identify the user. Also includes their contact details. | Name | Mandatory | Type | Description | |-------------|-----------|--------|---------------------------------------------------------------------------------------------------| | `reference` | + | string | Identifier of the user (payout recipient or payment sender) in your system (up to 128 characters) | | `contacts` | - | array | [User contacts](/reference/objects#customer_contact) | ## `customer_interaction` An object describing customer interaction. | Name | Mandatory | Type | Description | |------------|-------------------------------------|--------|------------------------------------------------------------------------| | `type` | + | string | Customer interaction type. Possible values: `redirect`, `inform` | | `redirect` | - (mandatory for `type = redirect`) | object | [User redirect data](/reference/objects#customer_interaction_redirect) | | `inform` | - (mandatory for `type = inform`) | object | [Payment option data](/reference/objects#customer_interaction_inform) | ## `data` Token and tokenized card details. | Name | Required | Type | Description | |--------|----------|--------|--------------------------------------------------------------| | `number` | + | object | [Token information](/reference/objects#tokenize_number) | ## `encrypted_card` Card with encrypted fields (tokenized). Transmitted during payouts or payments through the widget. | Name | Mandatory | Type | Description | |------------------------|-----------|--------|------------------------| | `number_hash` | \+ | string | Card number hash | | `expiration_date_hash` | \- | string | Expiration date hash | | `security_code_hash` | \- | string | CVC code hash | | `cardholder_name_hash` | \- | string | Cardholder's name hash | ## `fee` The fee charged. | Name | Mandatory | Type | Description | |----------------|-----------|--------|---------------------------------------------------------------| | `merchant_fee` | + | object | [Fee amount and currency](/reference/objects#merchant_fee) | ## `error` Error description object. | Name | Mandatory | Type | Description | |---------------|-----------|--------|-------------------| | `code` | \- | string | Error code | | `description` | \- | string | Error description | ## `faster_payment_system` Data of a user of the Faster Payment System for payouts and payments. | Name | Mandatory | Type | Description | |---------------|---------------------------|--------|-----------------------------------------------| | `phone` | - (mandatory for payouts) | string | Recipient's phone number | | `bank_id` | - (mandatory for payouts) | string | Identifier of the recipient's bank in the FPS | | `description` | - (*) | string | Payout or payment purpose (15 to 140 characters) | (*) To learn whether or not the `description` parameter is mandatory, contact your personal manager. ## `faster_payment_system_verification` Data for the recipient verification in the Faster Payment System. | Name | Mandatory | Type | Description | |-----------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------| | `phone` | \+ | string | Recipient's phone number | | `bank_id` | \+ | string | Identifier of the recipient's bank in the FPS | ## `fps_no_account_widget` Payment page data for money transfers. | Name | Mandatory | Type | Description | | ----------- | -------------- | ------ | --------------------------- | | `session_id` | + | string | Payment session identifier | ## `info` (tokenized bank card) Details of a tokenized bank card. Returns in response to the [`token/info`](/reference/methods#tokeninfo) request. | Name | Mandatory | Type | Description | |---------------|-----------|--------|-----------------------------| | `number_hash` | \+ | string | Card number hash obtained from the tokenization widget | | `brand` | \+ | string | Payment system, e.g. `visa` | | `last4` | \+ | string | Last 4 digits of the card number | | `type` | + | string | Token type. Always: `card` | ## `info` (public token) Information about a public token. Returns in response to the [`token/info`](/reference/methods#tokeninfo) request. | Name | Mandatory | Type | Description | |---------------|-----------|--------|--------------------------------------------------------------------------------------------| | `token` | \+ | string | Token | | `created_at` | \+ | string | Creation date in ISO 8601 format | | `finished_at` | \+ | string | Completion date in ISO 8601 format | | `is_active` | \+ | bool | Possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `type` | + | string | Token type. Always: `public_token` | ## `info` (token for recurring payments or payouts) Information about a token for [recurring payments](/payments/payment-recurring) and payouts. Returns in response to the [`token/info`](/reference/methods#tokeninfo) request. | Name | Mandatory | Type | Description | |---------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format | | `is_active` | + | bool | Whether it is possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | | `type` | + | string | Token type. Always: `recurrent_token` | ## `info` (tokenized card details) Tokenized card details. Returns in response to the [`tokenize/elements`](/reference/methods#tokenizeelements) request. | Name | Required | Type | Description | |----------------------|----------|--------|---------------------| | `masked_card_number` | + | string | Masked card number | | `card_network` | + | string | Card payment system | | `card_type` | + | string | Card type | ## `inform` Payment option data. | Name | Mandatory | Type | Description | |------|-----------|--------|--------------------------------------------------------------------------| | `qr` | - | object | [QR code for payments via FPS](/reference/objects#qr_inform_interaction) | ## `merchant_fee` Fee amount and currency. | Name | Mandatory | Type | Description | |------------|-----------|--------|----------------------------------------------------------------------------------------------| | `amount` | + | int | Amount in minor currency units (cents). If the fee is 1 USD, the value is `100` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `usd` | ## `metadata` This block may contain any additional information. May be a string, an integer, or an object. It is **mandatory** for transactions processed on behalf of submerchants or by a submerchant. In this case, pass the `submerchant` field. Any additional fields and their names are up to you—the fields below are just an example. | Name | Mandatory | Type | Description | |------------------------|-----------|--------|----------------------------------| | `submerchant` | + |string | Any unique value, for example, a URL of the payment site | | `merchant` | - |string | Merchant ID or name | | `merchant_order_id` | - |string | Order number | | `user_os` | - |string | User's operating system | | `user_location` | - |string | User's country | | `user_ip` | - |string | User's IP | Examples ```json showLineNumbers { "metadata": { "merchant": "", "submerchant": "https://submerchant-site-url.com" } } ``` ```json showLineNumbers { "metadata": { "merchant": "", "submerchant": "Game name" } } ``` ```json showLineNumbers { "metadata": { "submerchant": "https://submerchant-site.com", "merchant_order_id": "123123", "user_os": "android", "user_location": "DE", "user_ip": "127.0.0.1" } } ``` ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/init/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "35", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" }, "metadata": { "submerchant": "https://submerchant-site-url.com", "merchant_order_id": "123123", "user_os": "android", "user_location": "DE" } }' ``` ## `number` Token and tokenized card details. | Name | Required | Type | Description | |---------|----------|--------|------------------------------------------------------| | `token` | + | string | Token | | `info` | + | object | [Card information](/reference/objects#tokenize_info) | ## `participant_details` Payout participant details. | Name | Mandatory | Type | Description | |-------------|-----------|--------|-----------------------------------------------------| | `sender` | - | object | [Sender's details](/reference/objects#sender) | | `recipient` | - | object | [Recipient's details](/reference/objects#recipient) | ## `payment_details` The description of the method for performing the payment. | Name | Mandatory | Type | Description | |-------------------------|--------------------------------------------------|--------|---------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Payment method type. Possible values: `card`, `recurrent`, `faster_payment_system` | | `card` | - (mandatory for `type = card`) | object | [Bank card details](/reference/objects#card) | | `recurrent` | - (mandatory for `type = recurrent`) | object | [Details for repeating the payment using the token](/reference/objects#recurrent) | | `faster_payment_system` | - (mandatory for `type = faster_payment_system`) | object | [Payment via FPS](/reference/objects#faster_payment_system) | ## `payment_method` = `payout_details` >Use `payment_method` for API v1, and `payout_details` for API v2. The description of the method for receiving the payout. | Name | Mandatory | Type | Description | |------------------|-------------------------------------------|--------|-------------------------------------------------------------------------------------------------| | `type` | + | string | Type of method for receiving the payout. Possible values: `card`, `bank_account`, `recurrent`, `tokenized_card` | | `card` | - (mandatory for `type = card`) | object | [Recipient's bank card](/reference/objects#card) | | `bank_account` | - (mandatory for `type = bank_account`) | object | [Recipient's bank account](/reference/objects#bank_account) | | `recurrent` | - (mandatory for `type = recurrent`) | object | [Token data](/reference/objects#recurrent) | | `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | ## `payment_options` Parameters needed to perform the payment. | Name | Mandatory | Type | Description | |--------------|-----------|--------|-------------------------------------------------------------------------------------------------| | `return_url` | - | string | URL to which the user is redirected after the payment is performed **Mandatory for payments made without our payment widget** | | `recurrent` | - | bool | Determines whether the payment is to be performed using the saved token | | `platform_details` | - | object | [User device data](/reference/objects#platform_details) | ## `payments` = `payout_list` >Use `payments` for API v1, and `payout_list` for API v2. Payout details. | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Payout identifier | | `status` | + | string | Status. Possible values: `succeeded`, `in_progress`, `pending`, `failed` | | `created_at` | + | string | Creation date in ISO 8601 format | | `payment_method`/`payout_details` | + | object | [Method of receiving the payout](/reference/objects#payment_method) | | `amount_details` | + | object | [Amount](/reference/objects#amount_details) | | `amounts` | - | object | [Transaction fee](/reference/objects#amounts) | | `finished_at` | - | string | Completion date in ISO 8601 format | | `customer` | - | object | [Recipient's data in your system](/reference/objects#customer), e.g. the login that lets you verify the recipient on your side. | | `participant_details` | - | object | [The details of payout participants](/reference/objects#participant_details) required to perform the payout, e.g. the names and addresses of the payer and the recipient. | | `refunds` | - | array | [Refund list](/reference/objects#refunds) | | `transaction_info` | - | object | [Transaction details](/reference/objects#transaction_info) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata) | | `error` | - | object | [Error description](/reference/objects#error) |   #### Payout statuses (`status`) - `in_progress` — the payout is being processed. - `pending` — awaiting your confirmation ([`session/confirm`](/reference/methods#sessionconfirm)) or cancellation ([`session/cancel`](/reference/methods#sessioncancel)). - `succeeded` — the payout has been completed successfully. - `failed` — the payout has not gone through because of an error. ## `platform_details` User device data. | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | User's device type. Options: `desktop`, `mobile` | | `os` | + | string | User's operating system. Options: `ios`, `android`, `windows`, `linux` | | `browser` | + | string | User's browser. Options: `chrome`, `firefox`, `jivoMobile`, `microsoft edge`, `miui`, `opera`, `safari`, `samsung`, `webKit`, `weChat`, `yandex` | ## `public_token` Information about a public token. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | `token` | + | string | Token | ## `qr` QR code for payments via FPS. | Name | Mandatory | Type | Description | |-----------|-----------|--------|-----------------| | `content` | + | string | Link to QR code | | `img` | + | string | QR code body | ## `recipient` Payout recipient details. Which details are necessary depends on the method of receiving the payout. | Name | Mandatory | Type | Description | |------------------|---------------------------------------------------------------|--------|-------------------------------------| | `full_name` | - (mandatory for payouts to any cards) | string | Full name | | `first_name` | - | string | First name | | `last_name` | - | string | Last name | | `middle_name` | - | string | Patronymic | | `company_name` | - | string | Company name | | `reference` | - | string | Recipient identifier in your system | | `tax_reference` | - | string | Taxpayer identifier | | `beneficiary_id` | - (mandatory for the payments and payouts with a beneficiary) | string | INN of the beneficiary | | `country_iso3` | - | string | Country (ISO 3166-1 alpha-3) | ## `recurrent` (recurring transaction token) Token for recurring payments or payouts. Parent objects: [`payment_method`/`payout_details`](/reference/objects#payment_method), [`payment_details`](/reference/objects#payment_details). | Name | Mandatory | Type | Description | |-------------|-----------|--------|---------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | ## `recurrent` (recurring transaction token information) Information about a token for recurring payments or payouts. Parent arrays: [`acquiring_payments`/`payment_list`](/reference/objects#acquiring_payment). | Name | Mandatory | Type | Description | |---------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format | | `is_active` | + | bool | Whether it is possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | | `type` | + | string | Token type. Always: `recurrent_token` | ## `recurrent_token` Token for recurring payments or payouts. | Name | Mandatory | Type | Description | | -------- | -------------- | ------ | -------- | | `token` | + | string | Token | ## `redirect` User redirect data. | Name | Mandatory | Type | Description | |------------|-----------|--------------------------|-------------------------------------------------------| | `url` | \+ | string | Redirect address including GET parameters | | `base_url` | \+ | string | Redirect address | | `method` | \+ | string | Submission method. Possible values: `GET`, `POST` | | `qs` | \- | map<string,string> | Set of parameters depending on the transaction method | | `params` | \- | map<string,*> | Set of parameters depending on the transaction method | >- Check if any parameters are specified in the `qs` and `params` objects. >- Redirect the user to the redirect address specified in `base_url` using the method from the `method` parameter and including all the required parameters in the URL or request body. ## `refunds` An array with details on a refund. | Name | Mandatory | Type | Description | |--------------------|-----------|--------|--------------------------------------------------------------------------------| | `id` | \+ | string | Unique refund identifier | | `status` | \+ | string | Refund status. Possible values: `in_progress`, `accepted`, `declined`, `error` | | `amount_details` | \+ | object | [Amount of the refund](/reference/objects#amount_details) | | `created_at` | \+ | string | Creation date | | `finished_at` | \- | string | Completion date | | `is_chargeback` | - | bool | Whether the refund is made within a chargeback | | `transaction_info` | - | object | [Transaction details](/reference/objects#transaction_info) | #### Refund statuses (`status`) - `in_progress` – the refund is being processed. - `accepted` – the refund has been completed successfully. - `declined` – Pike has declined the refund. - `error` – the refund has not gone through because of an error. ## `ru` Bank account details (region: ru). | Name | Mandatory | Type | Description | |-------------|--------------------------------------------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `bik` | + | string | Recipient’s Bank Identification Code | | `account` | + | string | Recipient's bank account | | `full_name` | + | string | Individual's full name. For payouts to a sole proprietor's account, pass it in the following format: `ИП `. In case of a payout to a legal entity, enter the entity's name, if it is provided in the agreement. Important: if the name is passed incorrectly the recipient bank may cancel the payout and the payout will be refunded | | `description` | + | string | Payout purpose | | `inn` | - (mandatory for the payouts to the accounts of legal entities and sole proprietors) | string | Recipient's INN, 10 digits for legal entities, 12 digits for individuals, including sole proprietors | | `kpp` | - (mandatory for the payouts to the accounts of legal entities) | string | Recipient's Tax Registration Reason Code (KPP), 9 digits | ## `sber_pay` SberPay payment details. | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------| | `phone` | - | string | Phone number to send PUSH or SMS to. Format: `7**********` | | `channel` | + | enum | SberPay payment channel. Options: `app`, `mobile_web`, `web` | ## `sender` Payout payer details. Which details are necessary depends on the method of receiving the payout. | Name | Mandatory | Type | Description | |------------------|---------------------------------------------------------------|--------|---------------------------------------------| | `full_name` | - | string | Full name | | `first_name` | - | string | First name | | `last_name` | - | string | Last name | | `middle_name` | - | string | Patronymic name | | `company_name` | - | string | Company name | | `reference` | - | string | Sender identifier in your system | | `tax_reference` | - | string | Taxpayer identifier | | `beneficiary_id` | - (mandatory for the payments and payouts with a beneficiary) | string | INN of the beneficiary | | `country_iso3` | - | string | Country (ISO 3166-1 alpha-3) | | `city` | - | string | City | | `street` | - | string | Street and house number | | `postal_code` | - | string | Postal code (up to 6 digits) | | `email` | - | string | Sender's email | | `ipv4` | - | string | IP version 4 address of the sender's device | | `ipv6` | - | string | IP version 6 address of the sender's device | ## `session` A container with data about all the operations performed within a single payment session. Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund, or a payment which is subsequently split). | Name | Mandatory | Type | Description | |-----------------------------------|-----------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Session identifier | | `status` | + | string | Status. Possible values: `created`, `in_progress`, `accepted`, `cancelled`, `error` | | `created_at` | + | string | Creation date in ISO 8601 format | | `updated_at` | + | string | Update date in ISO 8601 format | | `payments`/`payout_list` | - | array | [A list of payouts performed within the session](/reference/objects#payments) | | `acquiring_payments`/`payment_list` | - | array | [A list of payments performed within the session](/reference/objects#acquiring_payment) | | `next_action` | - | string | Label indicating actions needed to perform the transaction successfully. Possible values: `confirm`, `capture` | | `error` | - | object | [Error description](/reference/objects#error) | #### Payment session statuses (`status`) - `created` — the session has been created and is waiting to be started or canceled. - `in_progress` — the session is being processed. - `accepted` — the session has been completed successfully. - `cancelled` — the session has been cancelled. - `error` — an unexpected error occurred while processing. >Attention! This status is not final. Please contact Pike's support team and wait for a final transaction status. #### Next steps (`next_action`) If this field is not empty, it means that Pike is waiting for you to perform specific actions to continue with the operation: - `confirm` — you need to confirm the operation ([`session/confirm`](/reference/methods#sessionconfirm)) or cancel it ([`session/cancel`](/reference/methods#sessioncancel)). - `capture` — you need to perform the debit ([`session/capture`](/reference/methods#sessioncapture)) or cancel it ([`session/cancel`](/reference/methods#sessioncancel)). ## `tokenized_card` A card token. | Name | Required | Type | Description | |-------|----------|--------|-------------| | `token` | + | string | Token | ## `tokenize_widget` Settings for the tokenization widget. | Name | Mandatory | Type | Description | | ------ | --------- | ---- | ------------------------------------------------------------------- | | `access` | \+ | bool | Identifies whether this public key can use the tokenization widget | ## `transaction_info` Transaction information. | Name | Mandatory | Type | Description | |-----------------|-----------|--------|-----------------------------------------------------------------------------------| | `rrn` | - | string | Retrieval Reference Number (a unique identifier generated for a bank transaction) | | `arn` | - | string | Acquirer Reference Number (a unique number assigned to credit card transactions) | | `auth_code` | - | string | Authorization code | | `fp_message_id` | - | string | Unique transaction identifier in FPS | ## `wallets` Your guarantee payment balance details (this balance is used to perform payouts). | Name | Mandatory | Type | Description | |------------------|-----------|--------|-------------------------------------------------------------------| | `id` | \+ | string | Balance identifier | | `amount_details` | \+ | object | [Current balance](/reference/objects#amount_details) | --- - [Methods](https://developer.pikepayments.com/en/reference/methods): Complete API method reference — session lifecycle (init, start, confirm, cancel, capture, refund), tokenize When processing requests, the validity of input parameters, the presence of [required headers](/reference/format), and the permissions to perform actions are checked. ## Transaction processing ### `recurrent/disable` #### Disabling a token Use this request to disable a token. Pass the token in the request, in the response you will get `is_active: false`. This means the token has been disabled, you cannot perform recurring payments/payouts with this token any longer. > After the token is disabled, the `finished_at` expiration date parameter may show a date related to the year 2000. This has no effect and can be ignored. #### Endpoint `/api/v1/recurrent/disable` #### Request parameters | Name | Mandatory | Type | Description | | --------- | -------------- | ----------------------------------------------------------------- | ----------------------------------------- | | `recurrent` | + | object | [The token to disable](/reference/objects#recurrent) | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/recurrent/disable \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-------------|-----------|--------|-----------------------------------------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `recurrent` | + | object | [Information about the token for recurring payments](/reference/objects#recurrent_token_info) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": false, "type": "recurrent_token" }, "status": "ok" } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/cancel` #### Cancel session You can send this request when Pike is ready to process a transaction—either a payout or a payment. For example, if you received a `ready_to_confirm` or `ready_to_capture` webhook. If you do not want to proceed with the transaction, you can cancel it by sending a `session/cancel` request. If everything is in order, send a request to confirm the transaction (`session/confirm`) or to capture the frozen amount (`session/capture`). #### Endpoint `/api/v1/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | -------------------- | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "cancelled", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2048", "status": "failed", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | -------------------- | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "cancelled", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2048", "status": "failed", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/capture` #### Debiting the amount put on hold You can use this request if you process hold payments. Such payments occur in two stages: first, the funds are frozen (e.g., on the user's bank card), and then they are debited upon your command. This request can be sent when Pike is ready to capture the funds and has sent you the `ready_to_capture` webhook. If you want to capture the frozen amount, send a `session/capture` request. You can capture the full frozen amount or only a part of it. To cancel the debit, send a `session/cancel` request. #### Endpoint `/api/v1/session/capture` #### Request parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Session identifier | | `amount_details` | - | object | [Amount](/reference/objects#amount_details). It can be less than the frozen amount but must be greater than 0. If the parameter is missing, the full frozen amount will be captured | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2048", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" } }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/capture` #### Request parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Session identifier | | `amount_details` | - | object | [Amount](/reference/objects#amount_details). It can be less than the frozen amount but must be greater than 0. If the parameter is missing, the full frozen amount will be captured | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2048", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" } }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/confirm` #### Confirming an operation You can send this request when Pike is ready to process a transaction—either a payout or a payment. For example, if you received the `ready_to_confirm` webhook. You need to check the transaction parameters and make a decision. If everything is in order, confirm the transaction by sending `session/confirm` to Pike. If something is wrong, cancel the transaction by sending a [`session/cancel`](/reference/methods#sessioncancel) request. #### Endpoint `/api/v1/session/confirm` #### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/confirm` #### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/create` #### Creating a payment session Send this request to create a payment session on Pike's side. Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within a session (e.g. several payouts, a payment and a refund, or a payment which is subsequently split). Use this request if you need to request data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. >If you are ready to pass the payout/payment parameters right away, you can do so: >For payments, pass `payment_details`, `amount_details`, and `customer`. >For payouts, pass `payment_method`/`payout_details` and `amount_details`. The response contains the parameters of a session created. #### Endpoint `/api/v1/session/create` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_method` | - | object | [Payout details](/reference/objects#payment_method) | | `payment_details` | - | object | [Payment details](/reference/objects#payment_details) | | `amount_details` | - | object | [Amount](/reference/objects#amount_details) in minor currency units (cents). To send 100 USD, specify `10000` | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/objects#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/objects#payment_options) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata) | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "order123" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z" } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/create` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payout_details` | - | object | [Payout details](/reference/objects#payment_method) | | `payment_details` | - | object | [Payment details](/reference/objects#payment_details) | | `amount_details` | - | object | [Amount](/reference/objects#amount_details) in minor currency units (cents). To send 100 USD, specify `10000` | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/objects#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/objects#payment_options) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata) | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "order123" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z" } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payment` #### Simultaneously creating a payment session and starting a payment Send this request to simultaneously create a payment session and start a payment. The response contains the parameters of a session created and information on the payment ([`acquiring_payments`/`payment_list`](/reference/objects#acquiring_payment)). #### Endpoint `/api/v1/session/init/payment` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | + | object | [Amount](/reference/objects#amount_details) in minor currency units (cents). To send 100 USD, specify `10000` | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | + | object | [Payer's data in your system](/reference/objects#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/objects#payment_options) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://pikepayments.com" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2048", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "payment_options": { "return_url": "https://pikepayments.com" } }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payment` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | + | object | [Amount](/reference/objects#amount_details) in minor currency units (cents). To send 100 USD, specify `10000` | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | + | object | [Payer's data in your system](/reference/objects#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/objects#payment_options) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://pikepayments.com" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2048", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "payment_options": { "return_url": "https://pikepayments.com" } }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payout` #### Simultaneously creating a payment session and starting a payout You can use this request if you are ready to provide all the parameters for creating a payout to a bank account or bank card. You can also initiate a payout using a token obtained during the creation of a recurring payment. The response contains the parameters of a session created and information on the payout (`payments`/`payout_list`). #### Endpoint `/api/v1/session/init/payout` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method` | + | object | [Payout data](/reference/objects#payment_method) | | `amount_details` | + | object | [Amount](/reference/objects#amount_details) in minor currency units (cents). To send 100 USD, specify `10000` | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/objects#customer) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2048", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payout` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `payout_details` | + | object | [Payout data](/reference/objects#payment_method) | | `amount_details` | + | object | [Amount](/reference/objects#amount_details) in minor currency units (cents). To send 100 USD, specify `10000` | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/objects#customer) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2048", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/refund` #### Refund Use this request to return money to the user after a successful payment. After completing the refund, Pike will send you a `payment_refunded` webhook. #### Endpoint `/api/v1/session/refund` #### Request parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Identifier of the session with the successful payment that needs to be refunded | | `amount_details` | - | object | [Amount of the refund](/reference/objects#amount_details). If not specified, the refund will be made for the full amount of the payment | | `metadata` | - | * | [Any additional information](/reference/objects#metadata) | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2048", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/refund` #### Request parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Identifier of the session with the successful payment that needs to be refunded | | `amount_details` | - | object | [Amount of the refund](/reference/objects#amount_details). If not specified, the refund will be made for the full amount of the payment | | `metadata` | - | * | [Any additional information](/reference/objects#metadata) | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2048", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/start/payment` #### Payment start Send this request to start a payment within an existing session. In the parameters, pass the data necessary to perform a payment or change any pieces of data already passed. #### Endpoint `/api/v1/session/start/payment` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | - (mandatory if not passed in `session/create`) | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | - (mandatory if not passed in `session/create`) | object | [Amount](/reference/objects#amount_details) | | `customer` | - (mandatory if not passed in `session/create`) | object | [Payer's data in your system](/reference/objects#customer) | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `payment_options` | - | object | [Additional payment parameters](/reference/objects#payment_options) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "30", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://pikepayments.com" }, "metadata": "good" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-08-21T06:21:36.913863Z", "updated_at": "2024-08-21T06:21:56.832509Z", "acquiring_payments": [{ "id": "pm_3232", "status": "in_progress", "created_at": "2024-08-21T06:21:56.846204Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "payment_options": { "return_url": "https://pikepayments.com" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` #### Endpoint `/api/v2/session/start/payment` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | - (mandatory if not passed in `session/create`) | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | - (mandatory if not passed in `session/create`) | object | [Amount](/reference/objects#amount_details) | | `customer` | - (mandatory if not passed in `session/create`) | object | [Payer's data in your system](/reference/objects#customer) | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `payment_options` | - | object | [Additional payment parameters](/reference/objects#payment_options) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "30", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://pikepayments.com" }, "metadata": "good" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-08-21T06:21:36.913863Z", "updated_at": "2024-08-21T06:21:56.832509Z", "payment_list": [{ "id": "pm_3232", "status": "in_progress", "created_at": "2024-08-21T06:21:56.846204Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "payment_options": { "return_url": "https://pikepayments.com" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` ### `session/start/payout` #### Payout start Send this request to start a payout within an existing session. In the parameters, pass the data necessary to perform a payout or change any pieces of data already passed. If you use the payout widget to obtain tokenized user bank card data, you can pass them in this request. #### Endpoint `/api/v1/session/start/payout` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_method` | - (mandatory if not passed in `session/create`) | object | [Payout data](/reference/objects#payment_method) (a card, bank account, etc.) | | `amount_details` | - (mandatory if not passed in `session/create`) | object | [Amount](/reference/objects#amount_details) | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/objects#customer) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2048", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/start/payout` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payout_details` | - (mandatory if not passed in `session/create`) | object | [Payout data](/reference/objects#payment_method) (a card, bank account, etc.) | | `amount_details` | - (mandatory if not passed in `session/create`) | object | [Amount](/reference/objects#amount_details) | | `participant_details` | - | object | [Information on the sender and recipient](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/objects#customer) | | `metadata` | - | * | [Any additional information](/reference/objects#metadata). If the transaction is processed by a submerchant, please specify the payment site: `"metadata": {"merchant": "","submerchant": "https://website"}` | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2048", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `token` #### Generating a public token Use this method to generate a public token to access Pike's JavaScript library and to work with the widgets. The token is valid for 24 hours. It can only be used for a single operation. In the request, pass the parameters for the widgets you are going to use with this token. #### Endpoint `/api/v1/token` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|---------------------------------------------------------------------------------------------------| | `tokenize_widget` | - | object | [Data required by the tokenization widget](/reference/objects#tokenizewidget) | | `acquiring_widget` | - | object | [Data required by the payment form widget](/reference/objects#acquiringwidget) | | `fps_no_account_widget` | - | object | [Data required by the payment form for money transfers](/reference/objects#fps_no_account_widget) | Request example Request example for creating a token to process a payment via a payment form ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_3230" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |----------------|-----------|--------|-----------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `public_token` | - | string | Public token | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539" } ``` Unsuccessful response example ```json showLineNumbers { "status": "error", "error": { "description": "acquiring_widget.session_id.not_unique", "code": "invalid_request" } } ``` ### `tokenize/elements` A method for tokenizing a card number with tokenized data stored on Pike's side. > To use this method, please contact your manager at Pike. #### Endpoint `/api/v1/tokenize/elements` #### Request parameters | Name | Mandatory | Type | Description | | --------------- | ---------------- | --------| ---------------- | | `card_elements` | + | array | [Bank card data for tokenization](/reference/objects#card_elements) | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/tokenize/elements \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "card_elements": [{ "ref": "number", "type": "card_number", "card_number": "4242424242424242" }] }' ``` #### Response parameters | Name | Mandatory | Type | Description | |----------|-----------|--------|----------------------------------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `data` | - | object | [Information about the token and the tokenized card](/reference/objects#tokenize_data) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "data": { "number": { "token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919", "info": { "masked_card_number": "424242******4242", "card_network": "visa", "card_type": "visa" } } } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ## Information ### `session/status` #### Getting full information on a payment session Send this request if you want to get full information on a payment session. For example, you can check whether the payout was completed, or check if you are able to debit the amount put on hold during a card payment. The response contains all the details on all the operations performed within the payment session. #### Endpoint `/api/v1/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/session/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", "payments": [{ "id": "po_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin": "123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v2/session/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/objects#payment_session) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", "payout_list": [{ "id": "po_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin": "123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `token/info` #### Getting token details Bank card transactions are often processed using tokenized data. Public tokens are created for payouts and payments through widgets, while recurring payment tokens are used for recurring transactions. You can retrieve information for any payment token, including: - Details about the bank card associated with the token—such as the masked card number and payment system. - Information about the token itself—its type, creation time, expiration date, and whether it is active at the time of the request. Use this method to learn the hidden card number and show the user from which card the funds will be debited, or to check the token expiration date. #### Endpoint `/api/v1/token/info` #### Request parameters | Name | Mandatory | Type | Description | |-------------------|--------------------------------------------|--------|-----------------------------------------------------------------------| | `type` | + | string | Request type. Options: `card`, `public_token`, `recurrent_token` | | `card` | - (mandatory for `type = card`) | object | [Bank card details](/reference/objects#card) | | `public_token` | - (mandatory for `type = public_token`) | object | [Public token details](/reference/objects#publictoken) | | `recurrent_token` | - (mandatory for `type = recurrent_token`) | object | [Recurring payment token details](/reference/objects#recurrent_token) | Request examples Send tokenized bank card data to get the card mask and payment system. ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "card_number_hash (token)" } } }' ``` Send a public token to get information about it. ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "public_token", "public_token": { "token": "your_token" } }' ``` Send a token for recurring payments/payouts to get information about it. ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "recurrent_token", "recurrent_token": { "token": "your_token" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |--------|-----------|--------|----------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `info` | - | object | Depending on the request type (`type`): - [card token information](/reference/objects#card_token_info)- [public token information](/reference/objects#public_token_info)- [information on the token for recurring payments](/reference/objects#info_recurrent) | | `error` | - | object | [Error description](/reference/objects#error) | Successful response examples ```json showLineNumbers { "status": "ok", "info": { "number_hash": "card_number_hash", "brand": "visa", "last4": "4242", "type": "card" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2024-03-17T14:10:56+03:00", "finished_at": "2024-03-18T14:10:56+03:00", "is_active": true, "type": "public_token" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2024-03-17T14:19:05+03:00", "finished_at": "2024-04-17T14:19:05+03:00", "is_active": true, "type": "recurrent_token" } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `wallet/balance` If you have wallets used for payouts, use this request to check your current Pike deposit balance. This is necessary in order to make sure there is enough money on the balance: - for payouts - for refunds If the amount is insufficient, you can top up your deposit. > The amount is returned in minor currency units. If the value is `10000`, the amount is 100 USD. #### Endpoint `/api/v1/wallet/balance` #### Request parameters | Name | Mandatory | Type | Description | | ----------------- | --------- | ------ | ---------------------------- | | `request_datetime` | + | string | Timestamp of the request in ISO 8601 | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/wallet/balance \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_datetime": "2019-10-14T19:53:00+03:00" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `wallets` | - | array | [List of guarantee payment accounts available at Pike](/reference/objects#wallets) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "wallets": [{ "id": "wl_1001", "amount_details": { "amount": 1500000, "currency": "usd" } }] } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Additional ### `sberpay/push` Method for requesting the payment status via SberPay. #### Endpoint `/api/v1/sberpay/push` #### Request parameters | Name | Mandatory | Type | Description | |--------------|-----------|--------|----------------------------------| | `session_id` | + | string | Session identifier | | `phone` | + | string | Phone number to send PUSH or SMS | Request example ```json showLineNumbers curl -X POST \ https://proxy-demo.pikepayments.com/api/v1/sberpay/push \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "phone": "79638594000" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |----------|-----------|--------|-----------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `error` | - | object | [Error description](/reference/objects#error) | Response example ```json showLineNumbers { "status": "ok" } ``` --- - [Webhooks](https://developer.pikepayments.com/en/reference/webhooks): Webhook event reference — payment_finished, payment_refunded, action_required, and more Our webhooks are notifications about events happening on Pike's side. Pike sends webhooks to inform you of the applied fee and the results of your operations, ask for confirmation, or alert you about actions you need to take. ## How to get webhooks To **start** getting webhooks, do the following: 1. In your system, create an address at which you want to receive the webhooks. 2. Inform your Pike manager of this address. To **stop using** the webhooks, inform your manager of your decision. :::info[] If you choose not to receive our webhooks, use the [`session/status`](/reference/methods#sessionstatus) method to get the payment session status. ::: ## What to send in response You are expected to send the 200 HTTP code in response to any webhook. If Pike receives a 4\*\* or 5\*\* code or no response, Pike will resend the webhook as follows: - the webhook will be resent repeatedly at intervals of increasing length (up to 15 minutes) - after 30 minutes Pike will stop resending the webhook :::info[] Additional fields may be added to the webhook payload over time, depending on the payment methods used. Make sure that your service can handle them without failure. ::: ## `action_required` Pike sends you this webhook when you or your users need to carry out certain actions to proceed with the operation. For example, the user might need to go through 3D Secure authentication when paying via a bank card. >The maximum waiting time for an action is 60 minutes. If the action does not occur within this time, the operation will automatically be completed with the `cancelled` status. #### Parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `type` | + | string | Webhook type: `action_required` | | `session` | + | object | [Payment session](/reference/objects#payment_session) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 15000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://pikepayments.com?foo=bar", "base_url": "https://pikepayments.com", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 15000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://pikepayments.com?foo=bar", "base_url": "https://pikepayments.com", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` ## `payment_finished` You receive this webhook when Pike has completed an operation. The webhook body contains all the details of the operation, including its final status (in the `status` field). For example, if you are sending a payout and have received the `succeeded` status in this webhook, it means that the payout has been completed successfully. #### Parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `type` | + | string | Webhook type: `payment_finished` | | `session` | + | object | [Payment session](/reference/objects#payment_session) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_1234", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2048", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "po_1234", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2048", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ## `payment_refunded` Pike sends you this webhook after performing a refund. It contains information on the payment session, including all the details about the refund. The webhook is sent in the following cases: - if the refund was made using the [`session/refund`](/reference/methods#sessionrefund) method - within the **chargeback** procedure > If the refund was made as part of the chargeback procedure, the `refunds` array will contain `"is_chargeback": true`. #### Parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `type` | + | string | Webhook type: `payment_refunded` | | `session` | + | object | [Payment session](/reference/objects#payment_session) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 1000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin": "123456" } }, "amount_details": { "amount": 1000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ## `ready_to_capture` Pike sends you this webhook after placing a hold on money in case of delayed capture payments. To debit the money, send a [`session/capture`](/reference/methods#sessioncapture) request. To cancel the payment, send a [`session/cancel`](/reference/methods#sessioncancel) request. #### Parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `type` | + | string | Webhook type: `ready_to_capture` | | `session` | + | object | [Payment session](/reference/objects#payment_session) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "capture", // highlight-next-line "acquiring_payments": [{ "id": "pm_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "capture", // highlight-next-line "payment_list": [{ "id": "pm_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "metadata": "good" }] } }' ``` ## `ready_to_confirm` You receive this webhook when Pike is ready to perform an operation. You need to check the operation parameters and either confirm the operation by sending a [`session/confirm`](/reference/methods#sessionconfirm) request or cancel the operation by sending a [`session/cancel`](/reference/methods#sessioncancel) request to Pike. >The maximum waiting time for a confirmation is 240 minutes. If no confirmation is received within this time, the operation will automatically be completed with the `cancelled` status. :::info[] For your convenience, you can use automatic payment session confirmation, when you are not required to get a `ready_to_confirm` webhook and then confirm it. To set up the automatic payment session confirmation, apply to your manager. ::: #### Parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------| | `type` | + | string | Webhook type: `ready_to_confirm` | | `session` | + | object | [Payment session](/reference/objects#payment_session) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payments": [{ "id": "po_1234", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "acquiring_payments": [{ "id": "pm_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payout_list": [{ "id": "po_1234", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payment_list": [{ "id": "pm_2048", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "metadata": "good" }] } }' ``` --- - [Error Codes](https://developer.pikepayments.com/en/reference/errors): Complete error code reference with descriptions, causes, and recovery actions > Please bear in mind that: > - The error codes may be changed without prior notice. > - Below are all the errors you can encounter when making either payments or payouts. > - The table below provides general descriptions for error codes (`code`), one error code can correlate with different values in the `description` field. > - The [`error`](/reference/objects#session-status) status of the payment session is not final. Please contact our support team and wait for a final transaction status. | Error code (`code`) | Error description | |----------------------------------------|--------------------------------------------------------------------------------------------------------------| | `3DS_error` | 3DS authentication failed | | `activity_count_exceeded` | The activity/amount limit for the card/wallet is exceeded | | `authentication_error` | An authentication error occurred | | `authorization_error` | An authorization error occurred | | `bank_card_expired` | The bank card is past its expiration date | | `cancelled_by_customer` | The transaction was canceled by the customer | | `capture_timeout` | The transaction was canceled as the confirmation timeout expired | | `card_number_does_not_exist` | The provided card number is invalid | | `confirm_timeout` | The confirmation timeout expired, the transaction was canceled | | `declined_by_issuer_bank` | The operation was declined by the issuing bank | | `idempotency_key_already_exists` | The previous request with the same key is still in progress. Wait till the previous request is processed | | `idempotency_key_not_supported` | This method cannot be used with an idempotency key | | `idempotency_key_params_mismatch` | The key has already been used for another session. Use another idempotency key | | `identification_error` | A partner identification error occurred | | `incomplete_data` | Some data is missing in the request. Please check your request for correctness | | `incorrect_card_data` | The provided card details are incorrect | | `insufficient_funds` | The card does not have enough funds | | `insufficient_wallet_balance` | There is not enough money on the balance. The error will be returned until the balance is topped up | | `internal_error` | An internal error occurred | | `invalid_details` | The transaction parameters are in the wrong format | | `invalid_request` | The request is invalid | | `invalid_recipient_details` | The recipient details are invalid | | `invalid_sender_details` | The sender details are invalid | | `invalid_transaction` | The transaction is invalid | | `issuer_bank_fault` | An error occurred on the issuing bank's side | | `not_permitted_by_issuer_bank` | The operation is not permitted by the issuing bank | | `not_permitted_to_card` | The transaction is not permitted for the card holder | | `operation_rejected` | The operation was rejected for security reasons | | `provider_exceeds_amount_limit` | The amount limit for the provider was exceeded | | `provider_foreign_transfer_prohibited` | A transfer to a foreign/corporate card for this provider is not allowed | | `provider_internal_error` | A provider error | | `provider_issuer_unavailable` | The provider issuer is unavailable | | `provider_timeout` | The provider timeout expired | | `qr_expired` | The QR code has expired. Start the payment over | | `refund_amount_too_large` | The refund amount exceeds the maximum allowed amount | | `repository_record_not_found` | The record was not found | | `routing_internal_error` | A payment condition determination error occurred | | `session_cancelled` | The session was canceled | | `session_cancelled_by_partner` | The session was canceled by the partner | | `session_wrong_state` | A transaction cannot be performed in this session status | | `suspected_fraud` | The transaction is suspicious | | `wallet_internal_error` | An error occurred while dealing with the balance | ---