Micro Challenge Deposits
Adding support for Micro Challenge Deposits (MCD)
If your account has been enabled to process Micro Challenge Deposit (MCD) verification requests, there is an additional step you must take to finish the verification process.
Create the initial bank authorization
The initial bank authorization does not change. Pass in the same establishData
object as was provided during the original authorization.
var establishData = {
accessId: {accessId},
requestSignature: {requestSignature},
merchantId: {merchantId},
description: 'transaction description',
merchantReference: 'merchant reference',
paymentType: 'Retrieval',
returnUrl: "https://yourapp.com/path/return",
cancelUrl: "https://yourapp.com/path/cancel"
};
Note: see the Securing Requests reference for details on how to calculate the requestSignature
Warning
Do not pass Consumer PII (name, email address, etc) in the
description
field. You can pass Consumer PII in thecustomer
object.
Handle the redirect
Once you get a successful redirect to your returnUrl
, confirm if the user needs to continue the verification process. Ensure the payment.paymentProvider.type
value is 2
(Manual Entry), the status
is 2
(Authorized), and the payment.account.verified
is false
. Because the payment.paymentProvider.type
is 2
(Manual Entry) and the payment.account.verified
value is false
, message to the user to return to your site when they are ready to verify their account.
Retrieving the test verification code
You can use our Sandbox Merchant Portal to view the test account verification deposit code that was generated for the Bank Authorization.
1. After signing into the Sandbox Merchant Portal, find the Bank Authorization transaction your created earlier.
2. Click on the Transaction ID to bring up the details. Scroll down to the 'Account Verification Deposits' section. Copy the 'Reference Code' value.
Initiate the verification flow
The following examples are using the JavaScript SDK. For guidance on building for mobile apps see the Mobile Apps guide.
1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId}
with the Access Id provided to you by Trustly):
<script src="https://sandbox.trustly.com/start/scripts/trustly.js?accessId={accessId}"> </script>
2. To provide optional Trustly configuration options, create a TrustlyOptions
object:
var TrustlyOptions = {
closeButton: false,
dragAndDrop: false,
widgetContainerId: "widget-container-id" //Page element container for the widget
};
For details on the Trustly configuration options, refer to the SDK Specification.
3. To provide the transaction details to the SDK, create an establishData
object:
var establishData = {
accessId: {accessId},
requestSignature: {requestSignature},
merchantId: {merchantId},
transactionId: {transactionId},
merchantReference: 'merchant reference',
returnUrl: 'https://merchant.com/trustly/return',
cancelUrl: 'https://merchant.com/trustly/cancel'
};
Tip
Ensure you're securing your call by including the
requestSignature
parameter.
4. Finally, call the Trustly SDK's establish
function:
Trustly.establish(establishData, TrustlyOptions);
The following is a full HTML page using the above example.
Info
You'll want to replace
{accessId}
and{merchantId}
with the values provided to you by Trustly
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script>
var TrustlyOptions = {
closeButton: false,
dragAndDrop: true,
widgetContainerId: 'widget',
};
</script>
<script src="https://sandbox.trustly.com/start/scripts/trustly.js?accessId={accessId}"></script>
</head>
<body style="margin: 0;">
<div id="widget"></div>
</body>
<script>
var establishData = {
accessId: {accessId},
requestSignature: {requestSignature},
merchantId: {merchantId},
transactionId: {transactionId},
merchantReference: 'merchant reference',
returnUrl: 'https://merchant.com/trustly/return',
cancelUrl: 'https://merchant.com/trustly/cancel'
};
Trustly.establish(establishData, TrustlyOptions);
</script>
</html>
Enter the test verification code
Using the verification HTML you created above, launch the Trustly Lightbox.
After entering the code retrieved from the Sandbox Merchant Portal and clicking OK, the user is directed back to your site.
Handle the redirect
Once you get a successful redirect to your returnUrl
, confirm if the user is indeed verified. Ensure the payment.paymentProvider.type
value is 2
(Manual Entry), the status
is 2
(Authorized), and the payment.account.verified
is true
. If payment.account.verified
is true
, the account is verified.
Testing
Trustly offers a Demo Bank in the Sandbox environment that can be used to trigger a number of testing scenarios. Read more in Testing.
Error Handling
Trustly uses conventional HTTP response codes to indicate success or failure of an API request.
HTTP Status Code | Description |
---|---|
200 OK | Everything worked as expected. |
400 Bad Request | Often due to a missing, required parameter. |
401 Unauthorized | Invalid accessId or accessKey. |
500 Server error | Something went wrong on Trustly's end. |
503 Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or server maintenance. |
Not all errors map cleanly onto HTTP response codes, however. In addition to the HTTP response code, Trustly returns an array of error objects that describes the errors as a JSON string such as the example below.
{
"errors": [
{
"domain" : "com.trustly.merchantgateway.v1.exception.InvalidParameterException",
"code" : 200,
"message" : "Could not find a transaction using Id 10000021"
}
]
}
Error Code | Description |
---|---|
100 | Internal error. An internal error (an internal database exception for example) occurred when trying to process the request. |
150 | Remote error. A remote error (the consumer's bank interface is down) occurred when trying to process the request. This is an internal error. |
200 | Invalid parameter error. One of the request parameters is invalid (sending an invalid amount format string for example). |
300 | Security error. These are generic security errors that can happen when trying to process the request. |
326 | Expired split token. |
330 | Invalid account. |
331 | Not enough balance. |
375 | Access control error. These occurs when some security parameter (accessId, accessKey or requestSignature) is invalid and the request cannot be processed. |
390 | Fraud analysis. Suspicious transaction or negative data. |
Updated 2 months ago