The Target365 SDK gives you direct access to our online services like sending and receiving SMS, address lookup and Strex payment transactions. The SDK provides an appropriate abstraction level for PHP and is officially support by Target365. The SDK also implements very high security (HMAC using RSA).
use Target365\ApiSdk\ApiClient;
$baseUrl = "https://shared.target365.io";
$keyName = "YOUR_KEY";
$privateKey = "BASE64_RSA_PRIVATE_KEY";
$apiClient = new ApiClient($baseUrl, $keyName, $privateKey);This example sends an SMS to 98079008 (+47 for Norway) from "Target365" with the text "Hello world from SMS!".
$outMessage = new OutMessage();
$outMessage
->setTransactionId(uniqid((string) time(), true))
->setSender('Target365')
->setRecipient('+4798079008')
->setContent('Hello World from SMS!');
$apiClient->outMessageResource()->post($outMessage);This example sets up a scheduled SMS. Scheduled messages can be updated or deleted before the time of sending.
$dateTime = new \DateTime();
$dateTime->add(\DateInterval::createFromDateString('1 hours'));
$sendTime = (new DateTimeAttribute($dateTime->format(\DateTime::ATOM)))->__toString();
$outMessage = new OutMessage();
$outMessage
->setTransactionId(uniqid((string) time(), true))
->setSender('Target365')
->setRecipient('+4798079008')
->setContent('Hello World from SMS!')
->setSendTime($sendTime);
$apiClient->outMessageResource()->post($outMessage);This example sends a donation payment SMS that costs 10 NOK.
$strex = new StrexData();
$strex
->setInvoiceText('Thank you for your donation')
->setMerchantId('YOUR_MERCHANT_ID')
->setAge(18)
->setPrice(10)
->setTimeout(10)
->setServiceCode('14002');
$outMessage = new OutMessage();
$outMessage
->setTransactionId(uniqid((string) time(), true))
->setSender('Target365')
->setRecipient('+4798079008')
->setContent('This message costs 10 NOK.');
->setStrex($strex);
$apiClient->outMessageResource()->post($outMessage);This example updates a previously created scheduled SMS.
$outMessage = $apiClient->outMessageResource()->get($transactionId);
$outMessage.content = $outMessage.content + " Extra text :)"
$apiClient->outMessageResource()->put($outMessage);This example deletes a previously created scheduled SMS.
$apiClient->outMessageResource()->delete($transactionId);If your service requires a minimum age of the End User, each payment transaction should be defined with minimum age. Both StrexTransaction and OutMessage have a property named “Age”. If not set or present in the request, there is no age limit.
This example creates a 1 NOK Strex payment transaction that the end user will confirm by replying "OK" to an SMS from Strex. You can use message_prefix and message_suffix custom properties to influence the start and end of the SMS sent by Strex.
$properties = new Properties();
$properties->message_prefix = "Dear customer...";
$properties->message_suffix = "Best regards...";
$transaction = new StrexTransaction();
$transaction
->setTransactionId(uniqid((string) time(), true))
->setShortNumber('2002')
->setRecipient('+4798079008')
->setMerchantId('YOUR_MERCHANT_ID')
->setPrice(1)
->setServiceCode('14002')
->setInvoiceText('Donation test')
->setSmsConfirmation(true)
->setProperties($properties);
$apiClient->strexTransactionResource()->post($transaction);This example creates a Strex one-time password sent to the end user and get completes the payment by using the one-time password. You can use MessagePrefix and MessageSuffix to influence the start and end of the SMS sent by Strex.
$transactionId = uniqid((string) time(), true);
$oneTimePassword = new OneTimePassword();
$oneTimePassword
->setTransactionId($transactionId)
->setSender('Target365')
->setRecipient('+4798079008')
->setMerchantId('YOUR_MERCHANT_ID')
->setMessagePrefix('Dear customer...')
->setMessageSuffix('Best regards...')
->setRecurring(false);
$apiClient->oneTimePasswordResource()->post($oneTimePassword);
/* Get input from end user (eg. via web site) */
$transaction = new StrexTransaction();
$transaction
->setTransactionId(uniqid((string) time(), true))
->setShortNumber('2002')
->setRecipient('+4798079008')
->setMerchantId('YOUR_MERCHANT_ID')
->setPrice(1)
->setServiceCode('14002')
->setInvoiceText('Donation test')
->setOneTimePassword('ONE_TIME_PASSWORD_FROM_USER');
$apiClient->strexTransactionResource()->post($transaction);This example reverses a previously billed Strex payment transaction. The original transaction will not change, but a reversal transaction will be created that counters the previous transaction by a negative Price. The reversal is an asynchronous operation that usually takes a few seconds to finish.
$reversalTransactionId = $apiClient->strexTransactionResource()->reverse($transactionId);This example gets a previously created Strex transaction to check its status. This method will block up to 20 seconds if the transaction is still being processed.
$transaction = $apiClient.strexTransactionResource()->get($transactionId);
$statusCode = transaction->getStatusCode();This example checks to the the Strex registration level for an end user. User validity is either Unregistered, Partial, Full or Barred. Some service codes and high amounts requires full registration.
$validity = $apiClient->strexRegistrationResource()->getUserValidity('YOUR_MERCHANT_ID', '+4798079008');This example sends a Strex registration SMS to an end user. Strex end user registration is required for some service codes and high amounts.
$registrationSms = new StrexRegistrationSms();
$registrationSms
->setMerchantId('YOUR_MERCHANT_ID')
->setTransactionId('YOUR_TRANSACTION_ID')
->setRecipient('+4798079008')
->setSmsText('Please register.');
$apiClient->strexRegistrationResource()->post($registrationSms);Please note:
-
The OneClick service will not stop same MSISDN to order several times as long as transactionID is unique. If end users order or subscribe several times to same service it's the merchants responsibility to refund the end user.
-
Recurring billing is initiated by merchants, see section Payment transactions for more info.
-
Since the one-click flow ends by redirecting the end user to an external merchant-controlled URL we recommend that merchants implement a mechanism to check status on all started transactions. If there’s any issue for the end user on their way to the last page they might have finished the payment, but not been able to get their product.
This example sets up a one-click config which makes it easier to handle campaigns in one-click where most properties like merchantId, price et cetera are known in advance. You can redirect the end-user to the one-click campaign page by redirecting to http://betal.strex.no/{YOUR-CONFIG-ID} for PROD and http://test-strex.target365.io/{YOUR-CONFIG-ID} for TEST-environment. You can also set the TransactionId by adding ?id={YOUR-TRANSACTION-ID} to the URL.
$config = new OneClickConfig();
$config
->setConfigId('YOUR_CONFIG_ID')
->setShortNumber('2002')
->setPrice(99)
->setMerchantId('YOUR_MERCHANT_ID')
->setServiceCode('14002')
->setInvoiceText('Donation test')
->setOnlineText('Buy directly')
->setOfflineText('Buy with PIN-code')
->setRedirectUrl('https://your-return-url.com?id={TransactionId}') // {TransactionId} is replaced by actual transaction id
->setSubscriptionPrice(99)
->setSubscriptionInterval('monthly')
->setSubscriptionStartSms('Thanks for donating 99kr each month.')
->setRecurring(true)
->setIsRestricted(false)
->setAge(18);
$apiClient->oneClickConfigResource()->put($config);If Recurring is set to 'false', the following parameters are optional:
-
SubscriptionInterval - Possible values are "weekly", "monthly", "yearly"
-
SubscriptionPrice - How much the subscriber will be charged each interval
This parameter is optional:
- SubscriptionStartSms - SMS that will be sent to the user when subscription starts.
This example sets up a recurring transaction for one-click. After creation you can immediately get the transaction to get the status code - the server will wait up to 20 seconds for the async transaction to complete.
$transactionId = uniqid((string) time(), true);
$transaction
->setTransactionId($transactionId)
->setRecipient("RECIPIENT_FROM_SUBSCRIPTION_TRANSACTION")
->setShortNumber('2002')
->setMerchantId('YOUR_MERCHANT_ID')
->setPrice(1)
->setServiceCode('14002')
->setInvoiceText('Donation test')
->setProperties($properties);
$apiClient->strexTransactionResource()->post($transaction);
$transaction = $apiClient->strexTransactionResource()->get($transactionId);
// TODO: Check transaction.StatusCodeThis example looks up address information for the mobile number 98079008. Lookup information includes registered name and address.
$lookup = $apiClient->lookupResource()->get('+4798079008');
$firstName = $lookup.firstName;
$lastName = $lookup.lastName;This example creates a new keyword on short number 2002 that forwards incoming SMS messages to 2002 that starts with "HELLO" to the URL "https://your-site.net/api/receive-sms".
$keyword = new Keyword();
$keyword
->setShortNumberId('NO-2002')
->setKeywordText('HELLO')
->setMode('Text')
->setForwardUrl('https://your-site.net/api/receive-sms')
->setEnabled(true);
$keywordId = $apiClient->keywordResource()->post($keyword);This example deletes a keyword.
$apiClient->keywordResource()->delete($keywordId);This example shows how SMS messages are forwarded to the keywords ForwardUrl. All sms forwards expects a response with status code 200 (OK). If the request times out or response status code differs the forward will be retried several times.
POST https://your-site.net/api/receive-sms HTTP/1.1
Content-Type: application/json
Host: your-site.net
{
"transactionId":"00568c6b-7baf-4869-b083-d22afc163059",
"created":"2019-02-07T21:11:00+00:00",
"sender":"+4798079008",
"recipient":"2002",
"content":"HELLO"
}
HTTP/1.1 200 OK
Date: Thu, 07 Feb 2019 21:13:51 GMT
Content-Length: 0
This example shows how delivery reports (DLR) are forwarded to the outmessage DeliveryReportUrl. All DLR forwards expect a response with status code 200 (OK). If the request times out or response status code differs the forward will be retried 10 times with exponentially longer intervals for about 15 hours.
POST https://your-site.net/api/receive-dlr HTTP/1.1
Content-Type: application/json
Host: your-site.net
{
"correlationId": null,
"transactionId": "client-specified-id-5c88e736bb4b8",
"price": null,
"sender": "Target365",
"recipient": "+4798079008",
"operatorId": "no.telenor",
"statusCode": "Ok",
"detailedStatusCode": "Delivered",
"delivered": true,
"billed": null,
"smscTransactionId": "16976c7448d",
"smscMessageParts": 1
}
HTTP/1.1 200 OK
Date: Thu, 07 Feb 2019 21:13:51 GMT
Content-Length: 0
Several methods exists for instantiating a DeliveryReport object from the received JSON:
try
{
// If the post request is received in the form of a PSR-7 Request:
$dlr = DeliveryReport::fromPsrRequest($request);
// Using php://input
$dlr = DeliveryReport::fromRawPostData($request);
// Or by simply passing in the received json string:
$dlr = DeliveryReport::fromJsonString($request);
}
catch (\InvalidArgumentException $e)
{
}Delivery reports contains two status codes, one overall called StatusCode and one detailed called DetailedStatusCode.
| Value | Description |
|---|---|
| Queued | Message is queued |
| Sent | Message has been sent |
| Failed | Message has failed |
| Ok | message has been delivered/billed |
| Reversed | Message billing has been reversed |
| Value | Description |
|---|---|
| None | Message has no status |
| Delivered | Message is delivered to destination |
| Expired | Message validity period has expired |
| Undelivered | Message is undeliverable |
| UnknownError | Unknown error |
| Rejected | Message has been rejected |
| UnknownSubscriber | Unknown subscriber |
| SubscriberUnavailable | Subscriber unavailable |
| SubscriberBarred | Subscriber barred |
| InsufficientFunds | Insufficient funds |
| RegistrationRequired | Registration required |
| UnknownAge | Unknown age |
| DuplicateTransaction | Duplicate transaction |
| SubscriberLimitExceeded | Subscriber limit exceeded |
| MaxPinRetry | Max pin retry reached |
| InvalidAmount | Invalid amount |
| OneTimePasswordExpired | One-time password expired |
| OneTimePasswordFailed | One-time password failed |
| SubscriberTooYoung | Subscriber too young |
| TimeoutError | Timeout error |