Create payin (legacy)

Creating a new payin

Create payin

POST {API_BASE_URL}/v1/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
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.date_of_birth*	date	Customer's date of birth in "yyyy-mm-dd" format
customer.phone.country_code*	string [2..4]	Country code of the customer's phone number, starting with "+"
customer.phone.number*	string [5..40]	Customer's phone number without the country code
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 [3..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
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"
  },
  "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/v1/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"
    },
    "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"
}'