+31 (0) 35 646 63 00 info@spilgames.com

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:

  • Status line: 200, and
  • Message body: [OK] (include the square brackets as well).

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.

Callback response parameters

Examples

Note

All code examples are syntactically correct, but they use dummy data values. When you copy-paste these examples, make sure you replace the dummy data with actual, valid data.
 

PHP POST data

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}:


$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
POST data

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:

  • OPEN
  • PAID
  • FAILED
  • PARTIAL
  • IGNORE
  • REFUND
  • NOT_REFUNDABLE

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:

  • 12 character long alphanumeric key;
  • It is unique.

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:

  • 1 (the user has at least one active subscription)
  • 0 (the user has no active subscriptions)

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