Receive Callback Notifications
In this section you become familiar with the following parts of the in-game payment integration procedure:
- The POST data returned by the payment callback when a payment reaches a specific status.
Info
When a payment reaches a specific status, the payment callback returns POST data to the game or the application.Use this information to validate the payment operation.Reply to this callback by sending a standard 200 OK HTTP response:
Send this reply to every payment notification you receive through the callback, regardless the reported payment status. When you reply to the callback URL with [OK], you stop receiving automated callback notifications for payment transactions. If you do not send this reply, callback POST data for payment transactions remain in the payment queue for 7 days/one week; during this period, callback notifications are sent on an hourly basis.
Examples
Note
This PHP code example shows how the POST data response is built. Notice how the hash is created ($myCalculatedHash variable), and then checked against the hash value included in the POST data to verify the transaction validity (if – else conditional flow statement}:
POST data$secret = 'd7e5aazq8klP'; // Your secret string. You use the same secret for all your games or applications. Contact Spil Games to request it.
$amount = $_POST['amount'];
$paidAmount = $_POST['paid_amount'];
$currency = $_POST['currency'];
$skuunit = $_POST['sku_unit'];
$skutype = $_POST['sku_type'];
$status = $_POST['status'];
$transactiontoken = $_POST['transaction_token'];
$userid = $_POST['user_id'];
$transactionid = $_POST['transaction_id'];
$myCalculatedHash = hash('sha256', "{$secret}{$amount}{$paidAmount}{$currency}{$skuunit}{$skutype}{$status}{$transactiontoken}{$userid}{$transactionid}");
if ($myCalculatedHash === $_POST['hash']) {
echo 'The hash checks out. The payment is valid.';
} else {
echo 'The hash is invalid. This payment does not originate from the Spil Games payment service. Do not process!';
} // End of the code example
Callback POST data example; the payment status is PAID:
(
[transaction_id] ⇒12345678 // Check this parameter to verify a transaction
[amount] ⇒ 123
[paid_amount] ⇒ 123
[game_id] ⇒ 175
[site_id] ⇒ 16
[channel_id] ⇒ 1
[package_id] ⇒ 12345
[sku_type] ⇒ MegaCoins
[sku_unit] ⇒ 100
[transaction_token] ⇒ unique-alphanumeric-string-1234
[custom_parameters] ⇒
[status] ⇒ PAID
[user_id] ⇒ phineasgauge1823
[internal_sku_name] ⇒ gamecoins
[created] ⇒ 2013-06-30 19:00:05
[lastmodified] ⇒ 2013-06-30 19:01:12
[paymentMethod] ⇒ sms
[provider] ⇒ payment-provider-name
[currency] ⇒ EUR
[hash] ⇒ f15da616592a0eb
[is_subscription] ⇒ 0
)
Callback response parameters
The table below lists the supplied POST parameters and their corresponding values.
| Name | Type | Included? | Definition |
|---|---|---|---|
| transaction_id | integer | Yes | The transaction ID.You receive the transaction ID value from Spil Games.Every time a new payment is initiated, a new transaction ID is issued.Use this parameter and the corresponding value to verify payments on your end.When you want to refer to a specific payment transaction, include the corresponding transaction ID value in your communication with the Spil Games support team assisting you.Example: 123 |
| amount | integer | Yes | The amount due, the total sum the user needs to pay to purchase the selected package.The value is in cents.Example: 800 |
| paid_amount | integer | Yes | The amount the user paid to purchase the selected package.The value is in cents.Example: 800 |
| game_id | integer | Yes | The game ID value, as sent by the game developer to Spil Games on their first request.Example: 203 |
| site_id | integer | Yes | The site ID value, as sent by the game developer to Spil Games on their first request.Example: 79 |
| channel_id | integer | Yes | The channel ID value, as sent by the game developer to Spil Games on their first request.Example: |
| package_id | integer | Yes | The package ID value, as sent by the game developer to Spil Games on their first request.Example: 42 |
| sku_type | string | Yes | The SKU type/name, as sent by the game developer to Spil Games on their first request.Example: coins |
| sku_unit | integer | Yes | The SKU measurement unit, as sent by the game developer to Spil Games on their first request.Example: 100 |
| transaction_token | string | Yes | Unique identifier for the payment selection screen instantiation.Every time the payment selection screen is triggered, a new transaction token is generated.This parameter returns the token ID value of the options object that you send as an argument when you make a showPaymentSelectionScreen call.Example: unique-alphanumeric-string-1234 |
| custom_parameters | key-value pairs | Yes | Extra custom parameters that you want to be returned in the callback.This parameter returns the params value of the options object that you send as an argument when you make a showPaymentSelectionScreen call. It can take up to 200 characters.If no custom parameters are defined in the showPaymentSelectionScreen call, the custom_parameters returned with the callback are empty. Example: key: value |
| status | string | Yes |
End status of the transaction.The allowed values are:
For further details, see Payment end statuses. In case of a partial payment, check the PARTIAL payment end status in Payment end statuses. Example: PAID |
| user_id | string | Yes | The user name value, as sent by the game developer to Spil Games on their first request.The user name string value is case-insensitive.This parameter returns the userId value of the options JSON object that you send as an argument when you make a showPaymentSelectionScreen call.The returned user name value always corresponds to the user name value given by the initial payment, which may be in a different upper-/lowercase sequence.Example: james_kirk |
| internal_sku_name | string | Yes | Internal SKU name for a specific SKU.The returned value identifies the pricing package the user selected and purchased.This value is not exposed to end users.Example: gamecoins |
| created | date | Yes | The creation date of the transaction, i.e. when the transaction was initiated.Date format: YYYY-MM-DD HH:MM:SSExample: 2013-06-30 19:00:05 |
| lastmodified | date | Yes | The date of the latest/most recent change or modification to the transaction information.Date format: YYYY-MM-DD HH:MM:SSExample: 2013-06-30 19:01:12 |
| paymentMethod | string | Yes | The payment method the end-user selected to carry out and complete the transaction.Example: sms |
| provider | string | Yes | The name or reference code of the payment provider service used to process the transaction.Example: paypal |
| currency | string | Yes | The three-letter currency code reference, as used in the payment transaction.Example: EUR |
| hash | string | Yes |
Each call requires a handshake hash, generated using the SHA-256 algorithm.The hash value is calculated using the parameters included in this table, and you can find the secret key in the payment administration tool, on Menu>Account>Publisher Information. The secret is a:
For further details, see Hash verification. Example: uniquealphanumericstring1234567890 |
| is_subscription | integer | Yes |
This parameter flags whether a user has any active subscriptions.Allowed values are:
Default value: 0 Example: 0 |
| multiplier | decimal | Yes | This parameter allows you to check if a promotion multiplier applies to the transaction.Default value: 1Example: 1.5 |