methods.md

API Methods and Types

##Table of contents

1. Pay
2. Reverse payment
3. Get payment status
4. Send verification code
5. Verify verification code
6. PreAuthorize
7. Get user information
   1. Get user information v1
   2. Get user information v2
   3. Get user information v3
   4. Get user information summary
8. Direct Payment Fault

Pay

Use the Pay method to directly charge a mobile subscription with a provided amount. It is also mandatory to specify a service code for a transaction that describes the category and in turn will effect the payout. The mobile subscription is charged immediately and you will get a synchronous response from the API. It is not necessary for the mobile phone to be turned on in order for the transaction to go through.

Note that some of our services requires the mobile phone subscription to be verified before use - see here for details.

Also please note that currently the following norwegian mobile network operators are supported through the API: Telenor, Telio (former Netcom) and Network Norway. Once the other norwegian mobile network operators start supporting Direct Payment, they will be automatically available for you through this API.

Request types

PaymentRequest

Name	Data Type	Description	Mandatory
ServiceCredentials	ServiceCredentials	For authentication purposes. This parameter is only relevant when using the SOAP endpoint. The REST interface gets the ServiceId from the request URL and Username/Password from the Authorization HTTP header.	Yes
PaymentDetails	PaymentDetails	Contains details about the payment.	Yes

ServiceCredentials

This type is only relevant when using the SOAP endpoint.

Name	Data Type	Description	Mandatory
ServiceId	Integer	Service ID, provided by Puzzel service desk.	Yes
Username	String	Username, provided by Puzzel service desk.	Yes
Password	String	Password, provided by Puzzel service desk.	Yes

PaymentDetails

Name	Data Type	Description	Mandatory	Version
Msisdn	String	The MSISDN that should be charged. The format should follow the ITU-T E.164 standard with a + prefix.	Yes	1, 2
Price	Integer	The amount that should be debited, in lowest monetary unit. Example: 100 (1,- NOK).	Yes	1, 2
ServiceCode	String	Service code identifying the type of transaction. See here for a list of available service codes	Yes	1, 2
ClientReference	String	Client reference for the transaction, must be unique.	Yes	1, 2
EndUserInvoiceText	String	Text that will be displayed on the end-user invoice.	No	1, 2
Age	Integer	The minimum age of the subscriber required for the purchase. If set, the valid values are 16 and 18.	No	1, 2
Differentiator	String	Arbitrary string set by the client to enable grouping of messages in certain statistics reports.	No	1, 2
InvoiceNode	String	Arbitrary string set by the client to enable grouping of messages on the service invoice.	No	1, 2
BusinessModel	String	Business model, a list containing the available business models is available here.	No	1, 2
AuthorizationToken	String	If the user has preauthorized the transaction, you can input the preauth token here. See [here](methods.md#preauthorize) for details.	No	2
SecurityLevel	Enum	Which security level the authorization request should use. 1 = None 2 = Confirmation (End user will have 1 minute to confirm the transaction) 3 = Pin (not in use)	Yes	2
ConfirmationChannel	Enum	If security level is set to 'Confirmation', you can specify which channel the confirmation message should use. 1 = USSD 2 = SMS	No	2
TeletorgSettings	TeletorgSettings	Parameters used for Teletorg (Premium voice services). See fields below.	No	2

TeletorgSettings

Name	Data Type	Description	Mandatory
Bnumber	String	The called number	No
StartTime	DateTime	Start time of the charged voice call. Format: YYYY-MM-DD HH:MM:SS	No
StartPrice	Integer	Start price for the charged voice call. Should be in lowest monetary unit. Example: 100 (1,- NOK)	No
Duration	Integer	Charged voice call duation in seconds	No

Response types

PaymentResponse

Name	Data Type	Description	Mandatory
ClientReference	String	Client reference that was set in the request.	Yes
TransactionId	Integer	Unique transaction ID.	Yes

Reverse payment

Use the Reverse payment method to cancel a payment already made. The transaction as a whole is then credited the mobile phone subscription. It is not possible to reverse only part of a payment.

Request types

Name	Data Type	Description	Mandatory
ServiceCredentials	ServiceCredentials	See here for details	Yes
ReversePaymentDetails	ReversePaymentDetails	Contains details about the transaction.	Yes

ReversePaymentDetails

Name	Data Type	Description	Mandatory
TransactionId	Integer	The unique transaction ID which was received in the payment response.	Yes

Response types

ReversePaymentResponse

Name	Data Type	Description	Mandatory
TransactionId	Integer	The unique transaction ID which was received in the payment response.	Yes

Get payment status

Use this method to get the payment status of a specific transaction. It can be useful in cases where something goes wrong in the payment or reverse payment flow and your client is unsure of the outcome of the operation.

Request types

PaymentStatusRequest

Name	Data Type	Description	Mandatory
ServiceCredentials	ServiceCredentials	See here for details	Yes
ClientReference	String	The unique client reference which was specified in the pay request.	Yes

Response types

PaymentStatusResponse

Name	Data Type	Description	Mandatory
ClientReference	String	The unique client reference which was specified in the payment status request.	Yes
PaymentStatus	Enum	Indicates the status of the payment. 0 = Not paid 1 = Paid 2 = Reversed	Yes
TransactionId	Integer	The unique transaction ID which was received in the payment response.	No

Send verification code

Some of our services requires that the mobile phone number to be charged is verified. This is to ensure that end-user do not enter a random mobile phone number to be charged. To verify a mobile phone number, use the "Send verification code" method which will generate a pin code and send it by sms to the specified mobile phone number. Your client must then provide the end user with an interface where the pin code can be entered and verified. Even though it is optional to set the expiration time when using this functionality, keep in mind that people change phone numbers every now and then, so we advise to set the expiration time to 1 year ahead in time.

Request types

Name	Data Type	Description	Mandatory
ServiceCredentials	ServiceCredentials	See here for details	Yes
Msisdn	String	The mobile subscription number to be verified.	Yes
ExpiryTime	DateTime	The expiration time for a verification. If this field is not used, the verification lasts forever.	No
Template	String	The template that should be used in the SMS, use {0} as the placeholder for the code. A default template will be used if this parameter isn’t specified. Example: Your verification code is {0}. Have a nice day!	No

Response types

N/A.

Verify verification code

Use this method to verify that the pin code entered by the end-user matches the pin code generated by the system.

Request types

Name	Data Type	Description	Mandatory
ServiceCredentials	ServiceCredentials	See here for details	Yes
Msisdn	String	The mobile subscription number associated with the verification code.	Yes
VerificationCode	String	The code to be verified.	Yes

Response types

N/A.

PreAuthorize

PreAuthorized payments are recurring payments where the End User have confirmed that the payment transactions (including premium SMS transactions) for a merchant can be executed without End User confirmation on each transaction.

This method returns a token to be used in subsequent Pay requests or Premium SMS requests. The token is issued by Strex and does not expire. However it can be manually invalidated by Strex in some situations if the Code of Conduct is violated.

Please note that the End User needs to be a user on the Strex platform for this to be successful.

NB This method is only available on the REST interface and it allows you to use the serviceId, username and password from either the SMS platform or Direct Pay platform. See the REST interface for details regarding authentication.

URI variables

Name	Data Type	Description
serviceId	String	The mobile subscription to generate a token for.
platform	Enum	Which platform the serviceId belongs to Accepts either int or string values: 0 = directpay 1 = sms

Request types

Name	Data Type	Description	Mandatory
Msisdn	String	The mobile subscription to generate a token for.	Yes
TransactionId	String	Your identifier for the request - is returned in the response.	Yes
Platform	Enum	Which Puzzel platform to validate ServiceCredentials against 0 = DirectPay 1 = Sms	Yes
SecurityLevel	Enum	Which security level the authorization request should use. 1 = None 2 = Confirmation 3 = Pin (not in use)	Yes
ConfirmationChannel	Enum	If security level is set to 'Confirmation', you can specify which channel the confirmation message should use. 1 = USSD 2 = SMS	No
ShortNumber	String	If ConfirmationChannel is set to 'SMS', you can specify the originator prefix of the sms message here. Default is '2222' from Strex. Note that Strex adds a 10 digit suffix, so you should only use 4 digit short codes here.	No
MessagePrefix	String	If ConfirmationChannel is set to 'SMS', you can specify a custom text that will be preceding the standard text provided by Strex.	No
MessageSuffix	String	If ConfirmationChannel is set to 'SMS', you can specify a custom text that will be proceeding the standard text provided by Strex.	No
TokenDescription	String	Information what the token is used for. This description is shown on Strex "Min side" and should describe the subscription service.	No
Age	String	The minimum age of the End User required for this request. If not set or present in the request, there is no age limit.	No

Response types

Name	Data Type	Description
ExternalTransactionReference	String	A unique transaction reference from Strex.
Token	String	The token to be used with subscription sell requests.
TransactionId	String	Your inputted identifier for the request.

Get user information

These methods returns various information from Strex regarding the End user and the subscription.

Note these methods are only available on the REST endpoint.

Get user information v1

Returns information about an end user's registration status on the Strex Payment Service.

Request

HTTP GET {host}/RestV1.svc/service/{serviceId}/msisdn/{msisdn}

Response object

Name	Data Type	Description
Msisdn	String	User's msisdn
Validity	Enum	0 = Not registered 1 = Registered, but not valid for licensed purchase 2 = Valid for licensed purchase 3 = MNO billing barred 4 = Verified user with BankID and valid for licensed purchase
TerminalType	String	Handset model.

Get user information v2

Runs an extensive "sell validation check" and provides an indicative response on whether the subscriber can be charged with the given input parameters.

Request

HTTP GET {host}/RestV1.svc/service/{serviceId}/msisdn/{msisdn}/userinfoV2

Query parameters

Name	Data Type	Description
amount	String	Amount you plan to charge the subscriber. Given in Norwegian øre (ie 2500 = 25 NOK)
serviceCode	String	Strex service code you plan to use when charging the subscriber.
age	Integer	Optional. If provided, age of the subscriber is checked to be above the input age.

Response

Returns HTTP 200 if okay with an empty body.

Get user information v3

Retrieves the current Strex transaction limits for an end user. The response is indicative. Only Strex limits is returned, MNO status is not checked (e.g. prepaid balance, payment card balance, cpa blocks, etc).

Request

HTTP GET {host}/RestV1.svc/service/{serviceId}/msisdn/{msisdn}/userinfoV3

Response object

Name	Data Type	Description
PreferredSourceOfFunds	Enum	-1 = Unknown 1 = MNO 2 = Not in use 3 = Payment card
SubscriptionType	Enum	-1 = Unknown 0 = Postpaid 1 = Prepaid
MaxAmountPrTransaction	Integer	Maximum amount (in øre) which can be charged in a single sell transaction.
RemainingMonthlyAmount	Integer	Remaining monthly amount (in øre) which can be charge for the subscriber before exceeding the monthly limit. 0 = limit already reached
RemainingYearlyAmount	Integer	Remaining yearly amount (in øre) which can be charge for the subscriber before exceeding the yearly limit. 0 = limit already reached -1 = no limit applicable, subscriber valid for purchase above defined yearly limit.

Get user information summary

Combines all the 3 "get user information" checks into one request and returns with 3 responses.

It is also possible to run a real Sell request of 2 NOK which automatically will be reversed through this request. This feature must be enabled by Puzzel personnel on the service. Note that such transactions will be visible on the end users invoice.

Request

HTTP GET {host}/RestV1.svc/service/{serviceId}/msisdn/{msisdn}/userinfoSummary

Query parameters

Name	Data Type	Description
amount	String	Amount you plan to charge the subscriber. Given in Norwegian øre (ie 2500 = 25 NOK)
serviceCode	String	Strex service code you plan to use when charging the subscriber.
Age	Integer	Optional. If provided, age of the subscriber is checked to be above the input age.

Response

HTTP status code 200 indicates that successfull requests have been made and you will get a response object as defined below. All other HTTP status codes indicates error, and HTTP status code 424 will return a DirectPaymentFault object.

Name	Data Type	Description
ResponseV1	Complex type	Returns the response object as defined in "Get user information" method
ResponseV1Fault	DirectPaymentFault	Returns any error codes from Strex on the "Get user information" request.
ResponseV2	Enum	An empty object (meaning success)
ResponseV2Fault	DirectPaymentFault	Returns any error codes from Strex on the "Get user information v2" request.
ResponseV3	Enum	Returns the response object as defined in "Get user information" method
ResponseV3Fault	DirectPaymentFault	Returns any error codes from Strex on the "Get user information v3" request.

DirectPaymentFault

Name	Data Type	Description	Mandatory
Code	Integer	Error code, please refer to the list of error codes for more details.	Yes
Description	String	Contains details about the error that occurred.	Yes