4 Billing & refund - success scenarios (API only)

These tests are only relevant if your integration does not require 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:

UK format

identificationMethodKey	GBR_BANGO
MSISDN	447710900120

USA format

identificationMethodKey	USA_BANGO
MSISDN	12025550120

4.1 Start then commit 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": "3.00",
                    "currencyIso3": "USD",
                    "financialBreakdown":
                    {
                        "taxAmount": "0.00",
                        "shippingAmount": "0.00"
                    }
                }
            ],
            "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}"
}

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

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.",
}

4.2 Start then cancel 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": "3.00",
                    "currencyIso3": "USD",
                    "financialBreakdown":
                    {
                        "taxAmount": "0.00",
                        "shippingAmount": "0.00"
                    }
                }
            ],
            "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}"
}

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

Cancel 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": "CANCELLED", 
    "responseMessage": "The transaction was cancelled successfully." 
}

4.3 Start, 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 { "bangoUserId": "123456789", "externalTransactionId": "{your-transaction-id}", "paymentMethods": [ "OPERATORBILLING", ], "paymentItems": [ { "priceList": [ { "grossAmount": "3.00", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "0.00", "shippingAmount": "0.00" } } ], "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}" }
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	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.", }
4	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." }

4.4 Start and partially commit 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": "3.00",
                    "currencyIso3": "USD",
                    "financialBreakdown":
                    {
                        "taxAmount": "0.00",
                        "shippingAmount": "0.00"
                    }
                }
            ],
            "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}"
}

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

Partially commit the transaction

Send a valid PUT request to https://api.bango.net/v5/transaction/{Bango-transaction-id} with a grossAmount or taxAmount lower than the POST

{
    "bangoUserId": "123456789",
    "externalTransactionId": "{your-transaction-id}",
    "paymentMethods": 
    [
        "OPERATORBILLING",
    ],
    "paymentItems":
    [
        {
            "priceList":
            [
                {
                    "grossAmount": "1.00",
                    "currencyIso3": "USD",
                    "financialBreakdown":
                    {
                        "taxAmount": "0.00",
                        "shippingAmount": "0.00"
                    }
                }
            ],
            "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.",
}

4.5 Start and partially commit a transaction then refund

NOTE: Partial commits are not supported by all payment providers.

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": "3.00", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "0.00", "shippingAmount": "0.00" } } ], "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}" }
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": "3.00", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "0.00", "shippingAmount": "0.00" } } ], "itemName": "Item name", "itemDescription": "Item description", "itemCategory": "1", "externalPaymentItemId": "{your-payment-item-id}", "submerchantReferenceKey": "{your-submerchant-reference-key}" } ], "extensionData": { } } }
3	Partially commit the transaction Send a valid PUT request to https://api.bango.net/v5/transaction/{Bango-transaction-id} with a grossAmount or taxAmount lower than the POST { "bangoUserId": "123456789", "externalTransactionId": "{your-transaction-id}", "paymentMethods": [ "OPERATORBILLING", ], "paymentItems": [ { "priceList": [ { "grossAmount": "1.00", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "0.00", "shippingAmount": "0.00" } } ], "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.", }
4	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." } The committed amount will be refunded to the user.

4.6 Start and commit a transaction then partial refunds

NOTE: Partial refunds are not supported by all payment providers.


{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
    "transactionId": "{Bango-transaction-id}"
}
{
    "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": "10.99",
                        "currencyIso3": "USD",
                        "financialBreakdown":
                        {
                            "taxAmount": "1.00",
                            "shippingAmount": "0.00"
                        }
                    }
                ],
                "itemName": "Item name",
                "itemDescription": "Item description",
                "itemCategory": "1",
                "externalPaymentItemId": "{your-payment-item-id}",
                "submerchantReferenceKey": "{your-submerchant-reference-key}"
            }
        ],
        "extensionData":
        {
        }                
    }
}
{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
}
{ 
    "responseCode": "REFUNDED", 
    "responseMessage": "The transaction was refunded successfully." 
}
{ 
    "responseCode": "REFUNDED", 
    "responseMessage": "The transaction was refunded successfully." 
}

4.7 Start and partially commit a transaction then partial refunds

NOTE: Partial commits or refunds are not supported by all payment providers.


{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
    "transactionId": "{Bango-transaction-id}"
}
{
    "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": "10.99",
                        "currencyIso3": "USD",
                        "financialBreakdown":
                        {
                            "taxAmount": "1.00",
                            "shippingAmount": "0.00"
                        }
                    }
                ],
                "itemName": "Item name",
                "itemDescription": "Item description",
                "itemCategory": "1",
                "externalPaymentItemId": "{your-payment-item-id}",
                "submerchantReferenceKey": "{your-submerchant-reference-key}"
            }
        ],
        "extensionData":
        {
        }                
    }
}
{ 
    "responseCode": "OK", 
    "responseMessage": "Success.",
}
{ 
    "responseCode": "REFUNDED", 
    "responseMessage": "The transaction was refunded successfully." 
}
{ 
    "responseCode": "REFUNDED", 
    "responseMessage": "The transaction was refunded successfully." 
}

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": "10.99", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "1.00", "shippingAmount": "0.00" } } ], "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}" }
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": "10.99", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "1.00", "shippingAmount": "0.00" } } ], "itemName": "Item name", "itemDescription": "Item description", "itemCategory": "1", "externalPaymentItemId": "{your-payment-item-id}", "submerchantReferenceKey": "{your-submerchant-reference-key}" } ], "extensionData": { } } }
3	Commit the transaction Send a valid PUT request to https://api.bango.net/v5/transaction/{Bango-transaction-id} with a grossAmount and or taxAmount lower than the POST { "bangoUserId": "123456789", "externalTransactionId": "{your-transaction-id}", "paymentMethods": [ "OPERATORBILLING", ], "paymentItems": [ { "priceList": [ { "grossAmount": "10.99", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "1.00", "shippingAmount": "0.00" } } ], "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.", }
4	Partially refund the transaction Send a valid DELETE request to https://api.bango.net/v5/transaction/{Bango-transaction-id} with a grossAmount and or taxAmount lower than the POST { "bangoUserId": "123456789", "externalTransactionId": "{your-transaction-id}", "paymentMethods": [ "OPERATORBILLING", ], "paymentItems": [ { "priceList": [ { "grossAmount": "1.59", "currencyIso3": "USD", "financialBreakdown": { "taxAmount": "0.20", "shippingAmount": "0.00" } } ], "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": "REFUNDED", "responseMessage": "The transaction was refunded successfully." } The requested amount will be refunded to the user.
5	Further partial refunds under remaining amount Subsequent partial refunds can be made up to the amount remaining from the original committed amount.	An HTTP response code 200 (OK) should be returned with the following body: { "responseCode": "REFUNDED", "responseMessage": "The transaction was refunded successfully." } The requested amount will be refunded to the user.