6 Billing & refund - success scenarios (redirect)



These tests are only relevant if your integration requires the user to be redirected via a Bango or Payment provider flow. This will be dependent on Payment Provider requirements.



To use Bango's test payment provider 'TestPay' to test these scenarios generate a userId using the following details:

identificationMethodKey

GBR_BANGOREDIRECT
MSISDN447710900180

6.1 Start, redirect user, then commit a transaction

Test

Action

Expected result

1

Start a transaction

Send a valid POST request to https://api.bango.net/v5/transaction

Optional: include a notificationUrl in the extensionData section to be notified when the user completes the redirect process.

{
    "bangoUserId": "123456789",
    "externalTransactionId": "{your-transaction-id}",
    "paymentMethods": 
    [
        "OPERATORBILLING",
    ],
    "paymentItems":
    [
        {
            "priceList":
            [
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
            ],
            "itemName": "Item title",
            "itemDescription": "Item description",
            "itemCategory": "1",
            "externalPaymentItemId": "{your-payment-item-id}",
            "submerchantReferenceKey": "{your-submerchant-reference-key}"
        }
    ],
    "extensionData":
        {
             "callbackUrl": "https://{callback-url}",
             "notificationUrl": "https://{notification-url}"
        }
}


An HTTP response code 202 (Accepted) should be returned with the following body:

{
  "responseCode": "CLIENT_ACTION_REQUIRED",
  "responseMessage": "An action is required in the client.",
  "transactionId": null,
  "parameters": {
    "action": "REDIRECT", 
    "url": "{redirect-the-end-user-to-this-url}"}
  }
}




2

(Optional) Retrieve transaction information

Send a GET request to https://api.bango.net/v5/transaction/{Bango-transaction-id}

No body required


An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "OK", 
    "responseMessage": "Success." ,
    "transaction":
    {
        "transactionId": "{Bango-transaction-id}",
        "bangoUserId": "123456789",
        "externalTransactionId": "{your-transaction-id}",
        "paymentMethod":
        {
            "type": "OPERATORBILLING",
            "key": "{network-name}",
            "description": "Direct operator billing",
            "parameters":
            {
            }
        },
        "paymentItems":
        [
            {
                "price":
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
                "itemName": "Item name",
                "itemDescription": "Item description",
                "itemCategory": "1",
                "externalPaymentItemId": "{your-payment-item-id}",
                "submerchantReferenceKey": "{your-submerchant-reference-key}"
            }
        ],
        "extensionData":
        {
        }                
    }
}


3

Redirect user

Send the user to the URL provided.

Confirm payment:

Enter ZIP and confirm payment:

After the user has completed any manual actions required they should be sent to your specified "callbackUrl" with externalTransactionId, transactionId and responseCode parameters appended.

https://{callback-url}/?externalTransactionId=
{your-transaction-id}&transactionId={bango-transaction-Id}
&responseCode=OK


The Bango API will also send a POST to the "notificationUrl" if one is provided in the initial request.

{
    "externalTransactionId": "{your-transaction-id}",
    "transactionId": "{bango-transaction-Id}",
    "responseCode": "{responseCode-from-available-api-codes}"
}
4

Commit the transaction

Send a valid PUT request to https://api.bango.net/v5/transaction/{Bango-transaction-id}

No body required


An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
}



6.2 Start, re-identify user via redirect, then complete a transaction

Test

Action

Expected result

1

Start a transaction

Send a valid POST request to https://api.bango.net/v5/transaction


{
    "bangoUserId": "123456789",
    "externalTransactionId": "{your-transaction-id}",
    "paymentMethods": 
    [
        "OPERATORBILLING",
    ],
    "paymentItems":
    [
        {
            "priceList":
            [
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
            ],
            "itemName": "Item title",
            "itemDescription": "Item description",
            "itemCategory": "1",
            "externalPaymentItemId": "{your-payment-item-id}",
            "submerchantReferenceKey": "{your-submerchant-reference-key}"
        }
    ],
    "extensionData":
        {
             "callbackUrl": "https://{callback-url}",
             "notificationUrl": "https://{notification-url}"
        }
}

An HTTP response code 400 (Bad request) should be returned with the following body:

{
 "responseCode": "INVALID_BANGOUSERID",
 "responseMessage": "Invalid bangoUserId."
}
2

Re-identify the user

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
    "merchantReferenceKey": "{your-appstore-identifier}",
    "mcc": "234",
    "mnc": "20",
    "thirdPartyUserId": "{your-user-id}",
    "deviceCapabilitySendSms": "true",
    "callbackUrl": "https://{callback-url}",
    "notificationUrl": "https://{notification-url}"
}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}",
    "bangoUserId": null,
    "parameters": 
    {
        "action": "REDIRECT",
        "url": "{redirect-url}"
    }
}


3 Send the user to the URL provided. After the user has completed any manual actions required they should be sent to your specified return URL. 
4

 Send POST request to https://api.bango.net/v5/identity/{sessionId}

No body required


 An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "OK",
    "responseMessage": "Success.",
    "sessionId": "{sessionId}",
    "bangoUserId": "123456789",
    "parameters": 
    {
    }
}


5

Start a transaction

Send a valid POST request to https://api.bango.net/v5/transaction

{
    "bangoUserId": "123456789",
    "externalTransactionId": "{your-transaction-id}",
    "paymentMethods": 
    [
        "OPERATORBILLING",
    ],
    "paymentItems":
    [
        {
            "priceList":
            [
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
            ],
            "itemName": "Item title",
            "itemDescription": "Item description",
            "itemCategory": "1",
            "externalPaymentItemId": "{your-payment-item-id}",
            "submerchantReferenceKey": "{your-submerchant-reference-key}"
        }
    ],
    "extensionData":
        {
             "callbackUrl": "https://{callback-url}",
             "notificationUrl": "https://{notification-url}"
        }
}


An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
    "transactionId": "{Bango-transaction-id}"
}
6

Commit the transaction

Send a valid PUT request to https://api.bango.net/v5/transaction/{Bango-transaction-id}

No body required



An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
}


6.3 Start, redirect user, commit then refund a transaction

Test

Action

Expected result

1

Start a transaction

Send a valid POST request to https://api.bango.net/v5/transaction

Optional: include a notificationUrl in the extensionData section to be notified when the user completes the redirect process.

{
    "bangoUserId": "123456789",
    "externalTransactionId": "{your-transaction-id}",
    "paymentMethods": 
    [
        "OPERATORBILLING",
    ],
    "paymentItems":
    [
        {
            "priceList":
            [
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
            ],
            "itemName": "Item title",
            "itemDescription": "Item description",
            "itemCategory": "1",
            "externalPaymentItemId": "{your-payment-item-id}",
            "submerchantReferenceKey": "{your-submerchant-reference-key}"
        }
    ],
    "extensionData":
        {
             "callbackUrl": "https://{callback-url}",
             "notificationUrl": "https://{notification-url}"
        }
}


An HTTP response code 202 (Accepted) should be returned with the following body:

{
  "responseCode": "CLIENT_ACTION_REQUIRED",
  "responseMessage": "An action is required in the client.",
  "transactionId": null,
  "parameters": {
    "action": "REDIRECT", 
    "url": "{redirect-the-end-user-to-this-url}"}
  }
}




2

(Optional) Retrieve transaction information

Send a GET request to https://api.bango.net/v5/transaction/{Bango-transaction-id}

No body required


An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "OK", 
    "responseMessage": "Success." ,
    "transaction":
    {
        "transactionId": "{Bango-transaction-id}",
        "bangoUserId": "123456789",
        "externalTransactionId": "{your-transaction-id}",
        "paymentMethod":
        {
            "type": "OPERATORBILLING",
            "key": "{network-name}",
            "description": "Direct operator billing",
            "parameters":
            {
            }
        },
        "paymentItems":
        [
            {
                "price":
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
                "itemName": "Item name",
                "itemDescription": "Item description",
                "itemCategory": "1",
                "externalPaymentItemId": "{your-payment-item-id}",
                "submerchantReferenceKey": "{your-submerchant-reference-key}"
            }
        ],
        "extensionData":
        {
        }                
    }
}


3

Redirect user

Send the user to the URL provided.

Confirm payment:

Enter ZIP and confirm payment:

After the user has completed any manual actions required they should be sent to your specified "callbackUrl" with externalTransactionId, transactionId and responseCode parameters appended.

https://{callback-url}/?externalTransactionId=
{your-transaction-id}&transactionId={bango-transaction-Id}
&responseCode=OK


The Bango API will also send a POST to the "notificationUrl" if one is provided in the initial request.

{
    "externalTransactionId": "{your-transaction-id}",
    "transactionId": "{bango-transaction-Id}",
    "responseCode": "OK"
}
4

Commit the transaction

Send a valid PUT request to https://api.bango.net/v5/transaction/{Bango-transaction-id}

No body required


An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
}
5

Refund the transaction

Send a valid DELETE request to https://api.bango.net/v5/transaction/{Bango-transaction-id}

No body required

An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "REFUNDED", 
    "responseMessage": "The transaction was refunded successfully." 
}


6.4 Start, re-identify user via redirect, then complete a transaction via redirect

Test

Action

Expected result

1

Start a transaction

Send a valid POST request to https://api.bango.net/v5/transaction

{
    "bangoUserId": "123456789",
    "externalTransactionId": "{your-transaction-id}",
    "paymentMethods": 
    [
        "OPERATORBILLING",
    ],
    "paymentItems":
    [
        {
            "priceList":
            [
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
            ],
            "itemName": "Item title",
            "itemDescription": "Item description",
            "itemCategory": "1",
            "externalPaymentItemId": "{your-payment-item-id}",
            "submerchantReferenceKey": "{your-submerchant-reference-key}"
        }
    ],
    "extensionData":
        {
             "callbackUrl": "https://{callback-url}",
             "notificationUrl": "https://{notification-url}"
        }
}


An HTTP response code 400 (Bad request) should be returned with the following body:
{
 "responseCode": "INVALID_BANGOUSERID",
 "responseMessage": "Invalid bangoUserId."
}
2

Re-identify the user

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
    "merchantReferenceKey": "{your-appstore-identifier}",
    "mcc": "234",
    "mnc": "20",
    "thirdPartyUserId": "{your-user-id}",
    "deviceCapabilitySendSms": "true",
    "callbackUrl": "https://{callback-url}",
    "notificationUrl": "https://{notification-url}"
}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}",
    "bangoUserId": null,
    "parameters": 
    {
        "action": "REDIRECT",
        "url": "{redirect-url}"
    }
}


3 Send the user to the URL provided. After the user has completed any manual actions required they should be sent to your specified return URL. 
4

 Send POST request to https://api.bango.net/v5/identity/{sessionId}

No body required


 An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "OK",
    "responseMessage": "Success.",
    "sessionId": "{sessionId}",
    "bangoUserId": "123456789",
    "parameters": 
    {
    }
}


5

Start a transaction

Send a valid POST request to https://api.bango.net/v5/transaction with new UserId

{
    "bangoUserId": "123456789",
    "externalTransactionId": "{your-transaction-id}",
    "paymentMethods": 
    [
        "OPERATORBILLING",
    ],
    "paymentItems":
    [
        {
            "priceList":
            [
                {
                    "grossAmount": "0.99",
                    "taxAmount": "0.00",
                    "currencyIso3": "USD"
                },
            ],
            "itemName": "Item title",
            "itemDescription": "Item description",
            "itemCategory": "1",
            "externalPaymentItemId": "{your-payment-item-id}",
            "submerchantReferenceKey": "{your-submerchant-reference-key}"
        }
    ],
    "extensionData":
        {
             "callbackUrl": "https://{callback-url}",
             "notificationUrl": "https://{notification-url}"
        }
}


An HTTP response code 200 (OK) should be returned with the following body:

{
  "responseCode": "CLIENT_ACTION_REQUIRED",
  "responseMessage": "An action is required in the client.",
  "transactionId": null,
  "parameters": {
    "action": "REDIRECT", 
    "url": "{redirect-the-end-user-to-this-url}"}
  }
}
6

Redirect user

Send the user to the URL provided.

Confirm payment:

Enter ZIP and confirm payment:

After the user has completed any manual actions required they should be sent to your specified "callbackUrl" with externalTransactionId, transactionId and responseCode parameters appended.

https://{callback-url}/?externalTransactionId=
{your-transaction-id}&transactionId={bango-transaction-Id}
&responseCode=OK


The Bango API will also send a POST to the "notificationUrl" if one is provided in the initial request.

{
    "externalTransactionId": "{your-transaction-id}",
    "transactionId": "{bango-transaction-Id}",
    "responseCode": "{responseCode-from-available-api-codes}"
}
7

Commit the transaction

Send a valid PUT request to https://api.bango.net/v5/transaction/{Bango-transaction-id}

No body required



An HTTP response code 200 (OK) should be returned with the following body:

{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
}