Before you start

Before you proceed with Creating a PayIn deal, make sure that you have completed the following steps:

• Creating a Service account
• Issuing a JWT token
• Managing JWT tokens
• Processing transactions

How to create a PayIn deal

The Create a Deposit (Pay-In) Deal method allows you to initiate a transaction where a client deposits a specified amount into the system, including various parameters such as currency, client details, and redirect URLs for handling different payment outcomes.

Follow these steps to create a deposit (pay-in) deal:

1. Set up your Authorization header:
   Include your Bearer token in the Authorization header:\
   

    Authorization: Bearer YOUR_ACCESS_TOKEN

2. Prepare your request:

   • Endpoint:\
     

     POST https://secure.sandbox.paymentsgate.io/deals/payin

   • Headers:
     • Content-Type: application/json
     • Authorization: Bearer YOUR_ACCESS_TOKEN
   • Request body parameters:
     • amount (required): Deal gross amount (how much money a client gives). Example: 100.00.
     • currency (required): The currency in which the client will transfer money. Example: "USD".
     • country (required): The country the client is from (ISO code). Example: "US".
     • invoiceId (required): Merchant invoice reference. Example: "INV123456".
     • clientId (required): Merchant client reference. Example: "CL123456".
     • successUrl (required): Redirect to this URL when payment successfully completes. Example: "https://merchant.com/success".
     • failUrl (required): Redirect to this URL when payment fails. Example: "https://merchant.com/fail".
     • backUrl (required): Redirect to this URL when the user presses the back button. Example: "https://merchant.com/back".
     • clientCard (required): Client card (masked). Example: "4111********1111".
     • bankId (optional): ID from bank list.
     • trusted (optional): Trusted flag (true or false).
     • type (optional): Payment type/FPS. Default is "p2p". Options include "p2p", "c2c", "iban", etc.
     • fingerprint (optional): Client fingerprint information.
     • lang (optional): Language of the payment widget (payment page). Options include "EN", "RU", "TR", etc.

3. Make the API call:\
   
   Example request:\
   

   curl --request POST \
     --url 'https://secure.sandbox.paymentsgate.io/deals/payin' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --data '{
       "amount": 100.00,
       "currency": "USD",
       "country": "US",
       "invoiceId": "INV123456",
       "clientId": "CL123456",
       "successUrl": "https://merchant.com/success",
       "failUrl": "https://merchant.com/fail",
       "backUrl": "https://merchant.com/back",
       "clientCard": "4111********1111"
     }'

   Example response: A successful response will return a JSON object containing the deal ID, status, redirect URL, and deal type.\
   

   bash

   {
     "id": "123e4567-e89b-12d3-a456-426614174000",
     "status": "new",
     "url": "https://paymentgateway.com/redirect",
     "type": "p2p"
   }

4. Perform error handling (if necessary): Be prepared to handle possible errors such as invalid tokens, missing parameters, or conflicts due to duplicate invoice IDs. Check the response status codes and error messages here to implement appropriate error handling in your application.
   Recommendations:

   • Validate input data: Ensure all required fields are included and correctly formatted in your request body.
   • Handle authentication: Check that your access token is valid and not expired before making the request.
   • Manage duplicate deals: Use unique invoiceId values for each deal to avoid conflicts.
   • Implement retry logic: For temporary issues, consider implementing retry logic with exponential backoff.

For more detail, please see the Create a Deposit (Pay-In) Deal API method description.