Skip to main content

Create a Payin Request

POST 
https://api.cleverhub.co/api/v2/payins

To be able to successfully create a payin request you would need the following APIs in consideration:

  • Step 1: Call the Get payin methods to retrieve the list of supported methods.
  • Step 2: Call the Get payin required fields to get specific required fields for each method.
  • Step 3: Create the payment using the method and required fields from the previous step.
  • Step 4: On sandbox environment, you can call the Simulate payin to simulate the payment.

Note:

If the payin_method_name is either jp_bank_jpy or au_payid_npp_aud, a pay_code will be sent to the webhook after a certain period with the following fields:

  • For jp_bank_jpy:
    • bank_name: The recipient's bank name.
    • transfer_id: The transfer identifier on the provider side.
    • branch_code: The code of the recipient's bank branch.
    • branch_name: The name of the recipient's bank branch.
    • account_number: The recipient's account number.
    • account_name: The recipient's account name.
    • expired_timestamp: The payment expiration time.
    • account_type: The recipient's account type.
    • transfer_name: The name associated with the transfer.
  • For au_payid_npp_aud:
    • payment_url: The payment url to complete the payment.

If you use one of the following payin methods, please check the list of supported providers before proceeding:

❗ Important:
For Step 3, if you choose mobile_money as the payin method, as the PayIn method, refer to the instructions in the Mobile Money tab.

  • For example: gh_mobile_money_ghs

Request​

Body

    currencystringrequired

    Transaction currency. It has to be a valid ISO 4217 currency codes. For example, 'PHP' for Philippine Peso, 'AUD' for Australian Dollar.

    gstbooleanrequired

    Goods and Services Tax.

    amountnumberrequired

    Amount. Optional with usdc_bank 's payin method name.

    namestringrequired

    Customer name.

    emailstringrequired

    If required_contact == true, this email must be the same email that was used to create the contact.

    external_idstring

    Custom ID.

    descriptionstringrequired

    Description.

    payin_method_namestringrequired

    Payin method name to be used for this payment. You will receive this from the Get payin methods API.

    payin_method_paramsobjectrequired

    Payin method parameters. You will receive this from the Get payin’s required fields API.

    webhook_notification object

    Merchant Callback Details

    endpoint_urlurl (endpoint_url)required

    An internet accessible url which Hello Clever will invoke when the status of the transaction has changed. The call will be done using the HTTP POST method. The endpoint exposed by the client must be TLS 1.2 and the server certificate must be issued by a well known commercial certificate authority and that self-signed or internally signed certs are not acceptable.

    Example: https://example.org
    authorization_header(authorization_header)required

    The string which Hello Clever will put into the Authorization request header when calling the Callback url.

    Example: SECRET
    expired_atYYYY-MM-DDTHH:mm:ss

    Expired time of transaction. This datetime would be in the UTC timezone. Must set the schedule bigger 15 minutes from the current time.

Responses​

Created

Schema
    uuidstring
    namestring
    descriptionstring
    emailstring
    external_idstring
    statuspending | received | expired | return_pending | return_received | return_expired | waiting

    Status of the transaction:

    • pending: Your customer hasn't made the requested payment yet.
    • received: Your customer has paid successfully. the funds have been settled into the merchant's available balance.
    • waiting: Your customer has paid successfully. The funds are waiting to be settled into the merchant's available balance.
    • expired: The payment request has expired.
    • return_pending: A full refund or partial refund request has been triggered on the payment.
    • return_received: The refund has been transferred to the original payee.
    • return_expired: The refund request has expired. Expiration time is set to be 10 days.
    • return_rejected: A refund failed due to problems with the destination account. HelloClever will not retry again.
    stageauthorize_otp | authorize_stk | normal_stage
    pay_code object

    Code using pay

    pay_urlstring
    currencystring
    gstboolean
    amountnumber
    gst_amountnumber
    totalnumber
    paid_amountnumber
    payment_methodstring
    is_refundableboolean
    expired_atdate-time
    pay_bydate-time
    webhook_notification object
    endpoint_urlstring
    authorization_headerstring

Callbacks​

POST 
{$request.body#/webhook_notification/endpoint_url}

If the merchant specifies values for the webhook_notification object during the Create payment request invocation, then a notification will be sent to the merchant's system when its status has changed to received or return_received.

The event will use webhook_notification.endpoint_url as endpoint and webhook_notification.authorization_header as Authorization header. We strongly recommend to use a different value for authorization_header on each payment request to increase the level of security.

This call is made by Hello Clever on the best effort basis. Hello Clever will implement retry mechanisms to ensure transient network failures do not affect the ability to call this endpoint. Hello Clever may call this endpoint more than once with the same payload so the merchant must ensure that the endpoint is implemented with idempotent behaviour always returning a 200 OK response even after subsequent calls.

If the target endpoint does not return HTTP 200, Hello Clever will retry the webhook call 3 times with 15 minutes delay per call.

Bodyrequired

    uuidstring

    Unique Id for the order created by Hello Clever system

    Example: VMMAOTFQ
    namestring

    Customer name.

    Example: Luyx.
    emailstring

    Customer email.

    Example: Luyx@helloclever.co.
    external_idstring

    Custom ID.

    Example: 123456
    statusreceived | return_pending | return_received

    Status of Payin.

    Example: received
    pay_code object

    Code using pay

    pay_urlstring
    Example: https://api.cleverhub.co/v1/shorted_url?hash=ApvZIZ9
    gstboolean

    GST for merchant.

    Example: true,
    currencystring

    Currency payin.

    Example: PHP
    amountnumber

    Amount.

    Example: 1000.0
    gst_amountnumber

    GST amount.

    Example: 100.0
    totalnumber

    Total amount.

    Example: 1100.0
    paid_amountnumber

    Paid Amount.

    Example: 1100.0
    descriptionstring

    Description

    Example: The message that you want to send to the payee.
    is_refundableboolean

    Available refund.

    Example: false,
    expired_atdate-time

    Expired time of payment. This datetime would be in the UTC timezone. Must set the schedule bigger 15 minutes from the current time.

    Example: 2021-12-23T06:00:00.000+0000
    pay_bydate-time

    Pay by time of payment. This datetime would be in the UTC timezone. Must set the schedule bigger 15 minutes from the current time.

    Example: 2021-12-23T06:00:00.000+0000
    webhook_notification object

    Payment request notification

    endpoint_urlstring

    Endpoint url

    Example: https://helloclever.co
    authorization_headerstring

    Authorization header

    Example: ****

Callbacks Responses​

The merchant's server should return this code

Authorization: app-id

name: app-idtype: apiKeydescription: The app-id is registered and secured inside Hello Clever system and only required when client has initiated or in the middle of the transaction.in: header
name: secret-keytype: apiKeydescription: The secret-key is our client's secret of the source. Required if a publishable key is used to retrieve the source.in: header
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cleverhub.co/api/v2/payins");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("app-id", "<app-id>");
request.Headers.Add("secret-key", "<app-id>");
var content = new StringContent("{\n  \"currency\": \"string\",\n  \"gst\": true,\n  \"amount\": 0,\n  \"name\": \"string\",\n  \"email\": \"string\",\n  \"external_id\": \"string\",\n  \"description\": \"string\",\n  \"payin_method_name\": \"string\",\n  \"payin_method_params\": {},\n  \"webhook_notification\": {\n    \"endpoint_url\": \"https://example.org\",\n    \"authorization_header\": \"SECRET\"\n  },\n  \"expired_at\": \"string\"\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Request Collapse all
Base URL
https://api.cleverhub.co/api
Auth
Body
{
  "currency": "string",
  "gst": true,
  "amount": 0,
  "name": "string",
  "email": "string",
  "external_id": "string",
  "description": "string",
  "payin_method_name": "string",
  "payin_method_params": {},
  "webhook_notification": {
    "endpoint_url": "https://example.org",
    "authorization_header": "SECRET"
  },
  "expired_at": "string"
}
ResponseClear

Click the Send API Request button above and see the response here!