Create Payment (POST Payment)

Merchants call this API to initiate a payment (create a transaction). The system routes the request by amount, payment method, country, and terminal type, and returns a unified body with result (code and message) and data (status, optional action for redirects / 3DS, and optional amount).

Request

• Method: POST
• Path: /api/v1/payin/createPayment
• Content-Type: application/json
• Auth: Include AppId, Timestamp, Signature headers as in Authentication

1. Request body fields

Root fields

Field	Type	Length / limits	Required	Description
merchantOrderId	string	≤ 64 chars	Yes	Merchant order ID (unique per merchant)
amount	object	—	Yes	Amount; see amount
country	string	2 chars, ISO-3166	Yes	Country/region code, e.g. CN
transInitiator	object	—	Yes	Terminal that initiates the payment; see transInitiator
paymentMethod	object	—	Yes	Payment method; see paymentMethod
userInfo	object	—	Conditional	User info; required when integrating the Payermax channel; see userInfo
notifyUrl	string	≤ 256 chars, URL	Yes	Async payment result notification URL
returnUrl	string	≤ 256 chars, URL	No	Redirect URL after payer completes payment
description	string	≤ 256 chars	No	Order description

amount object

Field	Type	Length / limits	Required	Description
value	string	Greater than 0, total string length ≤ 12	Yes	Amount in minor units (e.g. cents); must match currency rules. Values that violate rules (e.g. decimal-style amounts for zero-decimal currencies) are rejected upfront
currency	string	3 chars, ISO-4217	Yes	Currency, e.g. USD, PHP

Supported country/currency pairs: Country & currency.

transInitiator object

Field	Type	Length / limits	Required	Description
terminalType	string	enum	Yes	WEB, WAP, or APP
deviceType	string	enum	Conditional	Android or iOS. Required when paymentMethod.type is e-wallet and terminalType is WAP or APP
browserInfo	object	—	Conditional	Required for card payments when 3DS is not supplied by the merchant; see browserInfo

browserInfo object

(Under transInitiator.browserInfo, when required.)

Field	Type	Length / limits	Required	Description
acceptHeader	string	≤ 2048	Yes	Browser Accept header
colorDepth	string	2 chars	Yes	One of 1, 4, 8, 15, 16, 24, 32, 48
javaEnabled	boolean	—	Yes	Whether Java is enabled in the browser
language	string	≤ 8	Yes	e.g. from navigator.language, e.g. en-GB
screenHeight	string	≤ 6	Yes	Screen height in pixels
screenWidth	string	≤ 6	Yes	Screen width in pixels
timeZoneOffset	string	≤ 5	Yes	Offset between UTC and local browser time, in minutes

paymentMethod object

Field	Type	Required	Description
type	string	Yes	card, e-wallet, qr, onlineBanking, or bankTransfer. See Payment methods
e-wallet	object	Conditional	Required when type is e-wallet; see below
qr	object	Conditional	Required when type is qr; see below
onlineBanking	object	Conditional	Required when type is onlineBanking; see below
bankTransfer	object	Conditional	Required when type is bankTransfer; see below
card	object	Conditional	Required when type is card; see below
threeDS	object	Conditional	Required when type is card for 3DS strategy; see threeDS

In JSON, the e-wallet nested object key must be "e-wallet" (quoted).

paymentMethod.e-wallet object

Field	Type	Required	Description
paymentBrand	string	Yes	Enum: gcash only. See Payment brands

paymentMethod.qr object

Field	Type	Required	Description
paymentBrand	string	Yes	See Payment brands

paymentMethod.onlineBanking object

Field	Type	Required	Description
paymentBrand	string	Yes	See Payment brands

paymentMethod.bankTransfer object

Field	Type	Required	Description
paymentBrand	string	Yes	See Payment brands

paymentMethod.card object

Field	Type	Length / limits	Required	Description
cardNumber	string	≤ 19	Yes	Card number; required when card is sent
cvc	string	≤ 4	No	Security code
expiryDate	string	≤ 4	Yes	Expiry MMYY
holderName	string	≤ 50	No	Cardholder name

threeDS object

(Under paymentMethod.threeDS.)

Field	Type	Required	Description
threeDSStrategy	string	Yes	Force: force 3DS (inner); None: no 3DS (none); External: merchant-handled 3DS result

userInfo object

Field	Type	Length / limits	Required	Description
merchantUserId	string	≤ 128 chars	No	Unique merchant-side user identifier for risk control, payment instrument binding, repeat purchase recognition, and dispute tracking
phoneNumber	string	≤ 32 chars	No	User phone number
shopperIP	string	≤ 64	No	User IP
userAgent	string	≤ 2048	No	HTTP User-Agent value
email	string	≤ 254	No	User email
billingAddress	object	—	No	Billing address; may be required by some channels for identity; see billingAddress
name	object	—	No	Name; see name

billingAddress object

(Under userInfo.billingAddress. When this object is sent, fields marked Yes below must be provided.)

Field	Type	Length / limits	Required	Description
address	string	≤ 1024	No	Street / line address
city	string	≤ 50	Yes	City
country	string	2 chars	Yes	ISO-3166 country code, e.g. CN
postalCode	string	≤ 16	No	Postal code
stateOrProvince	string	≤ 3	No	State/province, ISO 3166-2
email	string	≤ 254	Yes	Email

name object

(Under userInfo.name.)

Field	Type	Length / limits	Required	Description
firstName	string	≤ 64	No	Given name
lastName	string	≤ 64	No	Family name

2. Request examples

E-wallet

When terminalType is WEB, omit deviceType. When paymentMethod.type is e-wallet and terminalType is WAP or APP, deviceType (Android or iOS) is required. When integrating the Payermax channel, userInfo is required.

{
  "merchantOrderId": "M202512180001",
  "amount": {
    "value": "1099",
    "currency": "HKD"
  },
  "country": "HK",
  "transInitiator": {
    "terminalType": "APP",
    "deviceType": "Android"
  },
  "paymentMethod": {
    "type": "e-wallet",
    "e-wallet": {
      "paymentBrand": "gcash"
    }
  },
  "userInfo": {
    "merchantUserId": "user_10001",
    "phoneNumber": "7151923499",
    "shopperIP": "112.198.100.1",
    "userAgent": "Mozilla/5.0 (Linux; Android 13; SM-S911B)",
    "email": "excample@gmail.com"
  },
  "notifyUrl": "https://merchant.com/webhook/payment",
  "returnUrl": "https://merchant.com/pay/result",
  "description": "MU ticket 2025-12-18"
}

Card (with browserInfo and threeDS)

{
  "merchantOrderId": "ORDER_20260330_153728_AO1002",
  "amount": {
    "value": "20",
    "currency": "PHP"
  },
  "country": "PH",
  "transInitiator": {
    "terminalType": "WEB",
    "browserInfo": {
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
      "colorDepth": "24",
      "javaEnabled": false,
      "language": "zh-CN",
      "screenHeight": "1440",
      "screenWidth": "2560",
      "timeZoneOffset": "480"
    }
  },
  "paymentMethod": {
    "type": "card",
    "card": {
      "cardNumber": "36563",
      "cvc": "123",
      "expiryDate": "1026",
      "holderName": "Bhns Josn",
      "threeDS": {
        "threeDSStrategy": "None"
      }
    }
  },
  "notifyUrl": "https://xxxxxx/api/v1/payin/test/webhook/notify",
  "returnUrl": "https://www.baidu.com",
  "description": "Test Order – Payment Testing",
  "userInfo": {
    "merchantUserId": "user_20001",
    "phoneNumber": "7151923499",
    "shopperIP": "178.49.15.251",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15) Gecko/20100101 Firefox/122.0",
    "email": "jane.brown307@example.com",
    "billingAddress": {
      "city": "New York",
      "country": "US",
      "email": "jane.brown307@example.com",
      "address": "123 Broadway Ave",
      "postalCode": "10001",
      "stateOrProvince": "NY"
    },
    "name": {
      "firstName": "Jane",
      "lastName": "Brown"
    }
  }
}

3. Response body

The response root has result and data:

Field	Type	Length / limits	Always returned	Description
result	object	—	Yes	Payment outcome (code and message)
data	object	—	—	Payment record; see fields below

result object

Field	Type	Length / limits	Always returned	Description
code	string	≤ 32 chars	Yes	Result code (success/failure identifier). See Response codes
msg	string	≤ 255 chars	Yes	Result message

data object

Field	Type	Length / limits	Always returned	Description
paymentId	string	≤ 64 chars	Yes	Velora platform payment ID
merchantOrderId	string	/	No	Merchant order ID
psp	string	/	No	PSP identifier that actually processes the order
channelOrderId	string	≤ 64 chars	No	Order ID on the PSP / channel side
status	string	Pending / Success / Failed	Yes	Current payment status
amount	object	—	No	Amount; may be returned on success or failure; see data.amount
action	object	—	No	Next step (redirect / 3DS); see data.action

data.amount object

Field	Type	Length / limits	Always returned	Description
value	string	Greater than 0, ≤ 12 chars	Yes when amount is present	Amount in minor units (e.g. cents); must match currency rules (invalid values such as fractional amounts for zero-decimal currencies are not accepted)
currency	string	3 chars, ISO-4217	Yes when amount is present	e.g. USD, PHP

data.action object

Field	Type	Length / limits	Always returned	Description
type	string	≤ 32	No	Redirect or threeDSRedirect
paymentUrl	string	≤ 255, URL	No	Pay-by-redirect URL; returned when action.type is Redirect
redirectUrl	string	≤ 1024	No	3DS authentication URL; returned when action.type is threeDSRedirect
expireAt	string	ISO-8601	No	Expiry time; passed through from the channel when provided

4. Response examples

Pending payment (Redirect)

{
  "result": {
    "code": "P0001",
    "msg": "Payment is processing."
  },
  "data": {
    "paymentId": "payin_202512180001",
    "merchantOrderId": "M202512180001",
    "psp": "omnipay",
    "channelOrderId": "OMNI202512180001",
    "status": "Pending",
    "action": {
      "type": "Redirect",
      "paymentUrl": "https://checkout.omnipay.com/pay/abc123",
      "expireAt": "2025-12-18T18:30:00+08:00"
    }
  }
}

Pending payment (threeDSRedirect)

{
  "result": {
    "code": "P0001",
    "msg": "Payment is processing."
  },
  "data": {
    "paymentId": "payin_202512180002",
    "merchantOrderId": "M202512180002",
    "psp": "bankcard_acquirer",
    "channelOrderId": "ACQ202512180002",
    "status": "Pending",
    "action": {
      "type": "threeDSRedirect",
      "redirectUrl": "https://acs.bank.example.com/3ds-challenge",
      "expireAt": "2025-12-18T18:30:00+08:00"
    }
  }
}

Success (with amount)

{
  "result": {
    "code": "S0000",
    "msg": "Success"
  },
  "data": {
    "paymentId": "payin_202512180003",
    "merchantOrderId": "M202512180003",
    "psp": "wallet_partner",
    "channelOrderId": "WALLET202512180003",
    "status": "Success",
    "amount": {
      "value": "1099",
      "currency": "HKD"
    }
  }
}

Creation failed (with amount example)

{
  "result": {
    "code": "P0012",
    "msg": "Transaction rejected by risk control"
  },
  "data": {
    "paymentId": "payin_202512180006",
    "merchantOrderId": "M202512180006",
    "psp": "risk_gateway",
    "channelOrderId": "RISK202512180006",
    "status": "Failed",
    "amount": {
      "value": "1099",
      "currency": "HKD"
    }
  }
}

For full description of result.code, see Response codes.

See also

• Country & currency: Supported countries and currencies
• Payment methods: Supported paymentMethod.type values
• Payment brands: paymentBrand inside e-wallet
• Order status: Status values and meanings
• Query order: Check status by paymentId or merchantOrderId
• Payment callback: Handle async payment notifications