Create payin (v2)

Creating a new payin

Create payin

POST {API_BASE_URL}/v2/merchants/payins/

Initiates a new payin (deposit transaction).

Headers

Name	Type	Description
x-merchant-id*	string
x-timestamp*	number
x-signature*	string	x-signature

Request Body

Name	Type	Description
reference_id	string [1..64]	Your internal transaction id which you may use to find the transaction easier
payment.amount*	number	Amount of the transaction
payment.currency*	enum	One of the Supported currencies
method	enum	One of the Supported methods
customer.id*	string [1..64]	Id of the customer in your system. You may use customer's email or their phone number if you don't have or don't want to provide a different identifier
customer.email*	string [6..255]	Customer's email address
customer.first_name*	string [2..80]	Customer's first name
customer.last_name*	string [2..80]	Customer's last name
customer.phone.country_code*	string [2..4]	Country code of the customer's phone number, starting with "+"
customer.phone.number*	string [4..40]	Customer's phone number without the country code
customer.date_of_birth*	date	Customer's date of birth in "yyyy-mm-dd" format
customer.address.addr_line_1*	string [3..64]	Customer's street address
customer.address.addr_line_2	string [3..64]	Customer's address extra data
customer.address.city*	string [1..40]	Customer's city
customer.address.state	string [2..40] / enum	Customer's state. Required for Canada (enum)
customer.address.zip*	string [3..12]	Customer's postal code
customer.address.country*	enum	Customer's country code in the 2-letter format (ISO 3166-1 alpha-2)
browser_data.user_agent*	string	Customer's current user agent
browser_data.ip_address*	string	Customer's current IP address. If incorrect, the customer will not be able to see the transaction details
webhook_url*	string	Your server URL where we will send server-side notifications
redirect_urls.fail*	string (url)	Customer will be redirected to this link when a transaction fails or gets canceled
redirect_urls.success*	string (url)	Customer will be redirected to this link after successfully completing a transaction
redirect_urls.in_progress	string (url)	Customer will be redirected to this link if they press "go back" while the transaction is in being processed and final result is not known yet
language	enum

201: Created Payin successfully created

{
  "id": "8ea802ab-267f-4145-8726-eba4d7d07da5",
  "reference_id": "id-in-merchant-system-485",
  "status": "new",
  "payment": {
    "amount": 49.23,
    "currency": "EUR"
  },
  "method": "card",
  "fee": null,
  "created_at": "2023-02-27T17:59:39.945246",
  "updated_at": "2023-02-27T17:59:39.945246",
  "expires_at": "2023-02-27T18:04:15.493103",
  "error_code": null,
  "error_message": null,
  "next_action": {
    "type": "string",
    "url": "string"
  }
}

400: Bad Request Payin initiation failed

Returns the respective error message with the error details.

401: Unauthorized Signature validation failed

Your signature generation may not be set up correctly or you are using an incorrect public or secret key.

403: Forbidden Access denied

Your merchant account may not have been fully set up. Please contact us for assistance.

422: Unprocessable Entity Invalid request

You might have issue with the integration. Please contact us and provide your request payload for investigation.

Example

curl -X POST 'https://api.dev.kitopay.com/api/v2/merchants/payins/' \
-H 'Content-Type: application/json' \
-H 'x-merchant-id: dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148' \
-H 'x-timestamp: 1601234567' \
-H 'x-signature: b3b7b638c8a755b3989011b6a5ff4cd0a94236764ee119724a6e0ea55c4e3c83' \
-d '{
    "reference_id": "tx-123",
    "payment": {
        "amount": 49.23,
        "currency": "EUR"
    },
    "method": "card",
    "customer": {
        "id": "1",
        "first_name": "Salvador",
        "last_name": "Dali",
        "date_of_birth": "1904-05-11",
        "email": "[email protected]",
        "phone": {
            "country_code": "+34",
            "number": "696123456"
        },
        "address": {
            "addr_line_1": "Placa Gala i Salvador Dali, 5",
            "city": "Figueres",
            "country": "ES",
            "zip": "17600"
        }
    },
    "redirect_urls": {
        "success": "https://website.com/cashier-result-page/success",
        "fail": "https://website.com/cashier-result-page/fail"
    },
    "webhook_url": "https://api.dev.website.com/webhooks/kitopay",
    "browser_data": {
        "ip_address": "195.138.66.113",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.2 Safari/605.1.15"
    },
    "language": "en"
}'