📝
Note
Prior to the API call

please ensure that you have an active merchant wallet, you may contact the sales team to activate the merchant wallet.

In order to top up the wallet balance, please visit the midtrans portal and you may see the Virtual Account as a top up destination.

Fetch Gems Balance

Path	/v1/mini-apps/gems/balance
Host	https://public-mini-app-merchants.gopayapi.com
Http Method	GET

Request Headers:

Property	Data type	Required	Description
Debug-Id	string	No	This is an identifier that is used for debugging purposes
Request-Id	string	Yes	This is an identifier that is used for maintaining idempotency
Authorization	string	Yes	Bearer Authorization header This is the token you would receive in the apply token API

Response:

Property	Data type	Description
success	boolean	It will be true if API call is successful and false in case of failure
data.balance	integer	User's gems balance. If success is false, this will be omitted
error	object	This object will be non-null only in case of failures
error.code	string	The error code
error.description	string	The description of the error

Sample Response:

Success Response:

{
    "data": {
        "balance": 1000000
    },
    "success": true
}

Error Response: With appropriate HTTP status codes. Only 5xx would be retriable

{
    "success": false,
    "error": {
        "code": "159",
        "description": "Payment option not found"
    }
}

Error codes:

Error code	Description
105	User not found
303	Malformed Authorization
900	Unable to process

Issue Gems Rewards

Path	/v1/mini-apps/rewards
Host	https://public-mini-app-merchants.gopayapi.com
Http Method	POST

Request Headers:

Property	Data type	Required	Description
Debug-Id	string	No	This is an identifier that is used for debugging purposes
Request-Id	string	Yes	This is an identifier that is used for maintaining idempotency
Authorization	string	Yes	Bearer Authorization header This is the token you would receive in the apply token API

Request Body:

Property	Data type	Required	Description
amount	object	Yes	It will be true if API call is successful and false in case of failure
amount.value	integer	Yes	A positive integer representing how much to charge in the smallest currency unit
description	string	Yes	Merchant given description for this cashback, string upto 256 characters.
amount.currency	string	Yes	Three-letter ISO 4127 currency code.smallest possible denomination Should be IDR for Indonesia.
reward_type	string	Yes	Identifies whether reward should be provided as emoney cashback or coins cashback Possible values : GOPAY_GEMS
metadata	object	No	Any map of string, string that merchant wants to reference in the order. But there are some required metadata to be passed. Required some mandatory metadata: • mini_app_name • activity_name

Response:

Property	Data type	Description
success	boolean	It will be true if API call is successful and false in case of failure
error	object	This object will be non-null only in case of failures
data	object	The object containing the reminder details
data.payment_id	string	The ID of the payment for reference
data.code	string	The error code
data.description	string	The description of the error

Sample Request:

{
  "amount": {
    "currency": "IDR",
    "value": 10000
  },
  "description": "Cashback for daily check-in",
  "reward_type": "GOPAY_GEMS",
  "metadata": {
    "mini_app_name": "GoPay Pet"
  }
}

Sample Response:

Success Response:

{
  "success": true
  "data": {
     "payment_id": "order-id"
   }
}

Error Response: With appropriate HTTP status codes. Only 5xx would be retriable

{
  "success": false,
  "error": {
    "description": "User not found"
  }
}

Error Response: 4060. It's non-retriable error.

{
  "success": false,
  "error": {
    "code": "4060",
    "description": "Fraud validation error"
  }
}

📝
Note
Error code 4060 — Cashback feature is temporarily disabled for this user. Please inform the user that they can’t receive cashback for the time being and suggest them to reach GoPay Help page for further information.

Collect Gems

Path	/v1/mini-apps/gems/collect
Host	https://public-mini-app-merchants.gopayapi.com
Http Method	POST

Request Headers:

Property	Data type	Required	Description
Debug-Id	string	No	This is an identifier that is used for debugging purposes
Request-Id	string	Yes	This is an identifier that is used for maintaining idempotency
Authorization	string	Yes	Bearer Authorization header This is the token you would receive in the apply token API

Request Body:

Property	Data type	Required	Description
amount	object	Yes	It will be true if API call is successful and false in case of failure
amount.value	integer	Yes	A positive integer representing how much to charge in the smallest currency unit
description	string	Yes	Merchant given description for this cashback, string upto 256 characters.
amount.currency	string	Yes	Three-letter ISO 4127 currency code.smallest possible denomination Should be IDR for Indonesia.
metadata	object	No	Any map of string, string that merchant wants to reference in the order. But there are some required metadata to be passed. Required some mandatory metadata: • mini_app_name • activity_name

Sample Request:

{
    "amount": {
        "currency": "IDR",
        "value": 1000
    },
    "description": "Gopay gems collect tesing",
    "metadata": {
        "mini_app_name": "GoPay Pet"
    }
}

Sample Response:

Success Response:

{
  "success": true
  "data": {
     "payment_id": "order-id"
   }
}

Error Response: With appropriate HTTP status codes. Only 5xx would be retriable

{
    "success": false,
    "error": {
        "code": "900",
        "description": "Internal server error"
    }
}