Gcash Mini Program Development PlatformGcash Mini Program Development PlatformDOCS

Data dictionary (for v2)

Model

Amount

Property

Data type

Required

Description

currency

String 

Yes

The three-character ISO-4217 currency code.

Max. length: 3 characters.

value

String 

Yes

A string that encloses a positive integer representing how much to charge in the smallest currency unit(e.g., 100 cents to charge $1.00 or 100 to charge $100, a zero-decimal currency).

Max. length: 16 characters.

ActionForm

Property

Data type

Required

Description

actionFormType

String

No

The action form type.

Enum: [ ORDER_CODE , REDIRECTION ]

orderCode

String 

No

The order code value. The order code is generated by merchants, which is a QR code with order information for customers to scan.

Max. length: 2048 characters.

redirectionUrl

String 

No

The URL of redirect.

Max. length: 4096 characters.

Env

Property

Data type

Required

Description

terminalType

String

No

The terminal type of this request.

Enum: [ MINI_APP, APP, WEB, WAP, SYSTEM ]

osType

String

No

OS type.

Enum: [ IOS, ANDROID ]

userAgent

String 

No

User agent.

Max. length: 1024 characters.

deviceTokenId

String 

No

Token ID of the device.

Max. length: 128 characters.

clientIp

String 

No

IP address of the client device.

Max. length: 64 characters.

cookieId

String 

No

User cookie ID.

Max. length: 128 characters.

storeTerminalId

String 

No

The store terminal ID.

Max. length: 64 characters.

storeTerminal

RequestTime

String/Datetime

No

The store terminal request time.

Max. length: 32 characters.

extendInfo

String 

No

Extend info.

Max. length: 4096 characters.

PaymentFactor

Property

Data type

Required

Description

needSurcharge

Boolean

No

An indicator of a surcharge, which appears in the request from APS to Mobile Payment Partner. If the value is TRUE, the fields surchargeAmount and surchargeQuote  must be specified. The default value is FALSE.

isPaymentEvaluation

Boolean

No

An indicator of the payment evaluation. If the value is TRUE, the payment is only to evaluate whether the payment can be successful and no actual funds deduction occurs. The default value is FALSE.

isAuthorizationAndPay

Boolean

No

An indicator of whether to do authorization for the agreement payment (Auto Debit) during the payment. The default value is FALSE.

isAuthorizationPayment

Boolean

No

An indicator of whether the payment is an authorization payment.The default value is FALSE.

isDeferredPayment

Boolean

No

An indicator of whether the payment is a deferred payment, in which scenario the user uses the product or service in advance.

needCheckCompliance

Boolean

No

An indicator of whether the payment information must be validated to meet compliances before the payment is processed.

needOtpVerification

Boolean

No

An indicator of whether the payment needs to verify OTP (one time password).

isCrossborderSettlement

Boolean

No

An indicator of whether the payment requires cross-border settlement.

inStorePaymentScenario

Boolean

No

An indicator of PaymentCode/OrderCode/EntryCode .

User

Property

Data type

Required

Description

userId

String 

No

The hashed unique identifier allocated for user.

Max. length: 64 characters.

status

String 

No

User status, Enum: "ACTIVE", "FROZEN", "INACTIVE"

Max. length: 32 characters.

nickName

String 

No

Nick name.

Max. length: 256 characters.

userName

UserName

No

User name, fullName and (firstName,middleName,lastName) can not both empty.

userAddresses

Array<Address>

No

The user's address information.

avatar

String 

No

Avatar url.

Max. length: 256 characters.

gender

String 

No

F: female; M: Male.

Max. length: 32 characters.

birthDate

String/Datetime

No

Birth date which follows the ISO 8601 standard.

Max. length: 32 characters.

nationality

String 

No

Nationality,  alpha-2 code according to ISO3166. e.g. JP, US.

Max. length: 32 characters.

loginIdInfos

Array<LoginIdInfo>

No

A list of user login IDs.

contactInfos

Array<ContactInfo>

No

A list of contact information.

extendInfo

String

No

The extend information,wallet and merchant can put extend info here.

Max. length: 4096 characters.

LoginIdInfo

Property

Data type

Required

Description

loginIdType

String 

Yes

The types of Login ID:

  • MOBILE_PHONE 
  • EMAIL 
  • OTHER

Max. length: 64 characters.

loginId

String 

No

An unique identifier for an user's ID login, which can be a mobile number or an email address. Users can use their login ID that without hidden bits to log in to the Wallet.

Max. length: 64 characters.

maskLoginId

String 

No

Mask Login ID that represents several bits of the phone number that are hidden to protect users' privacy.

Max. length: 64 characters.

hashLoginId

String 

No

Hash login ID that identifies an loginId  that is hashed by a hash algorithm. The external system can use it to compare its login ID that is hashed by the same hash algorithm to check whether the login ID is identical.

Max. length: 256 characters.

extendInfo

String 

No

The extensive information for wallets and merchants to add.

Max. length: 4096 characters.

ContactInfo

Property

Data type

Required

Description

contactType

String 

Yes

The followings are contact types that are available to all users：

  • MOBILE_PHONE 
  • TELEPHONE 
  • EMAIL 

Tips: Developer can add new types, but should consider the compatibility.

Max. length: 32 characters.

contactNo

String 

Yes

The value that corresponds to the contact type that is configured in the contactType  field. For example, this field can be mobile phone numer, or e-mail address.

Max. length: 64 characters.

extendInfo

String 

No

The extensive information for wallets and merchants to add.

Max. length: 4096 characters.

PaymentMethod

Property

Data type

Required

Description

paymentMethodType

String 

Yes

Payment method type, used to identifier a payment method.

Max. length: 32 characters.

paymentMethodId

String 

No

The uniqueId of a customer belong to a paymentMethod.

Max. length: 128 characters.

paymentMethodMetaData

String 

No

The payment method metadata.

Max. length: 2048 characters.

Result

Property

Data type

Required

Description

resultStatus

String

No

Result status. Valid values are:

  • S : Successful
  • F : Failed
  • U : Unknown
  • A : accepted, not yet succeed, but can proceed with some actions.

resultCode

String

No

Result code.

Max. length: 64 characters.

resultMessage

String

No

Result message that describes the result code in details.

Max. length: 256 characters.

UserName

Property

Data type

Required

Description

fullName

String 

No

Full Name.

Max. length: 128 characters.

firstName

String 

No

First Name.

Max. length: 32 characters.

middleName

String 

No

Middle Name.

Max. length: 32 characters.

lastName

String 

No

Last Name.

Max. length: 32 characters.

Order

Property

Data type

Required

Description

referenceOrderId

String

Yes

The unique identification of the order on the merchant side. It is used for the display of user consumption records, and the subsequent payment operations such as customer complaints and disputes track.

Max. length: 64 characters.

orderDescription

String

Yes

Description of the order used to display user consumption records, etc.

Max. length: 256 characters.

orderAmount

Amount

Yes

The amount of an order, like how much to charge in the specified currency unit for an order.

orderCreateTime

String/Datetime

No

Order create time from merchant which follows the ISO 8601 standard.

Max. length: 32 characters.

merchant

Merchant

Yes

Merchant information.

goods

Array<Good>

No

Goods information.

shipping

Shipping

No

Shipping information.

buyer

Buyer

No

Buyer information.

env

Env

No

The order environment information, such as the device information.

extendInfo

String 

No

Extended infomation data, this field includes information that are not common but needed for special use cases.

Max. length: 2048 characters.

Transaction

Property

Data type

Required

Description

transactionResult

Result

Yes

The transaction result, which contains information related to the business result and error information.

transactionType

String

Yes

Transaction type for each subsequent payment activity.

transactionRequestId

String

No

The unique ID assigend by merchant to identify the transaction request. When the transaction type is CAPTURE, the value of this field is identical to captureRequestId. When the transaction type is REFUND, the value of this field is identical to refundRequestId.

transactionId

String

Yes

The unique ID assigned by wallet to identify a transaction. When the transaction type is CAPTURE, the value of this field is identical to captureId. When the transaction type is REFUND, the value of this field is identical to refundId.

transactionStatus

String

No

Transaction status type.

transactionAmount

Amount

Yes

Transaction amount. When the transaction type is CAPTURE, the value of this field is identical to captureAmount. When the transaction type is REFUND, the value of this field is identical to refundAmount.

transactionTime

Date

No

Transaction time

isLastCapture

String

No

Only for capture transaction

voidSource

String

No

void source

extendInfo

String

No

The extensive information. The wallet and merchant can put extensive information in this property.

Max. length: 4096 characters.

Merchant

Property

Data type

Required

Description

referenceMerchantId

String 

Yes

Merchant ID.

Max. length: 32 characters.

merchantMCC

String 

Yes

Merchant MCC ( merchant category code).

Max. length: 32 characters.

merchantName

String 

Yes

Name of Merchant.

Max. length: 256 characters.

merchantDisplayName

String 

No

Display name of merchant.

Max. length: 64 characters.

merchantAddress

Address

No

The address of merchant.

merchantRegisterDate

String /Datetime

No

Merchant register time from merchant which follows the ISO 8601 standard.

Max. length: 32 characters.

store

Store

No

Merchant store.

Address

Property

Data type

Required

Description

region

String 

Yes

Alpha-2 code according to ISO3166. e.g. JP, US.

Max. length: 2 characters.

state

String 

No

State/County/Province.

Max. length: 8 characters.

city

String 

No

City/District/Suburb/Town/Village.

Max. length: 32 characters.

address1

String 

No

Address line 1(Street address/PO Box/Company name).

Max. length: 256 characters.

address2

String 

No

Address line 2(Apartment/Suite/Unit/Building).

Max. length: 256 characters.

label

String 

No

Label for address, e.g home, company.

Max. length: 64 characters.

zipCode

String 

No

ZIP or postal code.

Max. length: 32 characters.

extendInfo

String 

No

The extend information of goods.

Max. length: 4096 characters.

Store

Property

Data type

Required

Description

referenceStoreId

String 

Yes

The store belongs to a merchant, and the ID assigned by the corresponding merchant to the store is unique under the merchant.

Max. length: 64 characters.

storeName

String 

No

Name of store.

Max. length: 256 characters.

storeMCC

String 

No

Store business category code.

Max. length: 32 characters.

storeDisplayName

String 

No

Display name of store.

Max. length: 64 characters.

storeTerminalId

String 

No

Unique identifier of store's terminal.

Max. length: 64 characters.

storeOperatorId

String 

No

Unique identifier of store's terminal operator.

Max. length: 64 characters.

storeAddress

Address

No

The address of the store.

storePhoneNo

String 

No

Phone number of Store.

Max. length: 16 characters.

Goods

Property

Data type

Required

Description

referenceGoodsId

String 

Yes

Unique ID of goods.

Max. length: 64 characters.

goodsName

String 

Yes

Name of goods.

Max. length: 256 characters.

goodsCategory

String 

No

Category of goods.

Max. length: 256 characters.

goodsBrand

String 

No

Brand of goods.

Max. length: 32 characters.

goodsUnitAmount

Amount

Yes

Order amount for display of user consumption records, payment results page.

goodsQuantity

String 

No

Quantity of goods.

Max. length: 32 characters.

goodsSkuName

String 

No

Goods sku name.

Max. length: 64 characters.

goodsUrl

String 

No

Goods url.

Max. length: 1024 characters.

extendInfo

String 

No

The extend information of goods.

Max. length: 2048 characters.

Shipping

Property

Data type

Required

Description

shippingName

UserName

Yes

Shipping name.

shippingAddress

Address

Yes

Shipping address.

shippingCarrier

String 

No

The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.

Max. length: 128 characters.

shippingPhoneNo

String 

No

Recipient PhoneNo(including extension).

Max. length: 16 characters.

shippingFee

Amount

No

Shipping fee.

Buyer

Property

Data type

Required

Description

referenceBuyerId

String 

No

Unique Identification of buyer.

Max. length: 64 characters.

buyerName

UserName

No

Buyer name.

buyerPhoneNo

String 

No

Mobile phone number of buyer.

Max. length: 24 characters.

ContentTemplate

Property

Data type

Required

Description

templateParameters

Map<String,String>

No

A string-to-string mapping. The data structure is in JSON format: 

"templateParameters": {"key": "value"}  

, where: 

  • key : represents the variable that is defined in the template.
  • value : is used to replace the value of the  key parameter in the template.

language

String

No

RFC 1766, such as zh-CN, en-US.

RedirectActionForm

Property

Data type

Required

Description

method

String

No

The HTTP method. The value is POST  or GET .

parameters

String 

No

The parameters that are required for the HTTP method, which is in the key:value  pair format.

Max. length: 2048 characters.

redirectUrl

String 

Yes

The URL of redirect.

Max. length: 2048 characters.

Message

Property

Data Type

Required

Description

messageId

String

Yes

The unique ID is generated by Mini Program Platform to identify a notification.

  • Maximum length: 64 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.

Note: This field is an API idempotency field. For the notifications which are sent with the same requestId and reach an S status, the native app must return the same messageId.

See the Idempotency for details about API idempotency.

customerId

String

Yes

The unique ID is generated by the native app to identify a user.

Example: 218820000000000000023.

Maximum length: 32 characters.

messageChannel

MessageChannel

Yes

The channels to send a notification, including push, SMS, and Inbox.

templateCode

String

No

Indicates the template ID that is generated by Mini Program Platform to identify a template.

  • Maximum length: 64 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.
  • Can be Null.

messageContent

String 

Yes

The specific content that a notification to send.

Maximum length: 4096 characters.

  • Push

{

 "en-US": {

   "title": "testTitle",

   "content": "testContent",

   "linkUrl": "testUrl"

 },

 "zh-CN": {

   "title": "testTitle",

   "content": "testContent",

   "linkUrl": "testUrl"

 }

}

  • SMS

{

 "en-US": {

   "content": "this is sms content"

 },

 "zh-CN": {

   "content": "this is sms content"

 }

}

  • Inbox

{

 "en-US": {

   "displayType": "inbox_item_content",

   "header": {

     "appIcon": "icon url",

     "appName": "icon name",

     "msgBizName": "test_biz",

     "target": {

       "path": "header link url"

     }

   },

   "body": {

     "title": "message title",

     "content": "message content",

     "target": {

       "path": "message path url"

     }

   },

   "footer": [

     {

       "linkName": "link name",

       "target": {

         "path": "header link url"

       }

     }

   ]

 },

 "zh-CN": {

   "displayType": "inbox_item_content",

   "header": {

     "appIcon": "icon url",

     "appName": "icon name",

     "msgBizName": "test_biz",

     "target": {

       "path": "header link url"

     }

   },

   "body": {

     "title": "message title",

     "content": "message content",

     "target": {

       "path": "message path url"

     }

   },

   "footer": [

     {

       "linkName": "link name",

       "target": {

         "path": "header link url"

       }

     }

   ]

 }

}

extendInfo

String 

No

The extended information.

  • Maximum length: 4096 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.
  • Can be Null.

MessageSendResult

Property

Data Type

Required

Description

messageId

String 

Yes

The unique ID is generated by Mini Program Platform to identify a notification.

  • Maximum length: 64 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.

Note: This field is an API idempotency field. For the notifications which are sent with the same requestId and reach an S status, the native app must return the same messageId.

See the Idempotency for details about API idempotency.

success

Boolean

Yes

Indicates whether the notification is successfully sent to the native app. Valid values are:

  • true: The notification is sent successfully.
  • false: The notification fails to send.

retry

Boolean

No

Indicates whether the native app allows you to retry when the notification fails to send. Valid values are: 

  • true: The native app server allows to retry under specific scenarios, for example, when there are system exceptions.
  • false: The native app server does not allow to retry. For example, when the delivery frequency of the notification is beyond the limits set by the native app, retry is not allowed.

Note: This field is required when the value of the success field is false.

Enum

OsType

Key

Description

IOS

iOS.

ANDROID

Android.

PaymentMethodType

Key

Description

BALANCE

Balance.

COUPON

Coupon.

CREDIT_CARD

Credit Card.

DEBIT_CARD

Debit Card.

TerminalType

Key

Description

MINI_APP

Mini program.

APP

Mobile Application.

WEB

Broswer Web.

WAP

Mobile Wap.

SYSTEM

System Call.

MessageChannel

Key

Description

SMS

SMS

PUSH

PUSH

INBOX

INBOX