Create payout

Creating a new payout

Create payout

POST {API_BASE_URL}/v2/merchants/payouts/

Initiates a new payout (withdrawal 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.phone.number*	string [5..40]	Customer's phone number without the country code
customer.phone.country_code*	string [2..4]	Country code of the customer's phone number, starting with "+"
customer.email*	string [6..255]	Customer's email address
customer.last_name*	string [2..80]	Customer's last name
customer.first_name*	string [2..80]	Customer's first name
webhook_url*	string	Your server URL where we will send server-side notifications
redirect_urls.success	string (url)	Required only for payment page integration type. Customer will be redirected to this link after successfully completing a transaction
redirect_urls.fail	string (url)	Required only for payment page integration type. Customer will be redirected to this link after successfully completing a transaction

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/v2/merchants/payouts/' \
-H 'Content-Type: application/json' \
-H 'x-merchant-id: dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148' \
-H 'x-timestamp: 1601234567' \
-H 'x-signature: 27b50557de800b45f61e54fa4d748dd890a18592dfd53480523886802bce92ab' \
-d '{
    "reference_id": "tx-123",
    "payment": {
        "amount": 49.23,
        "currency": "EUR"
    },
    "customer": {
        "id": "1",
        "first_name": "Salvador",
        "last_name": "Dali",
        "email": "[email protected]",
        "phone": {
            "country_code": "+34",
            "number": "696123456"
        },
    },
    "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"
}'