Jump to

• Request
• Response
• Examples

Create a Balance Transfer

post

/bcws/webresources/v1.0/billunits/balancegroups/transferbalance

Creates a balance transfer.

Request

There are no request parameters for this operation.

Supported Media Types

• application/xml
• application/json

Request Body - application/xml ()

The details of the balance transfer to create. The minimum required parameters are:

• sourceRef
• targetRef
• transferAmount

The source and target can be balance group IDs, account IDs, account numbers, service IDs, or service numbers/MSISDN numbers.

Root Schema : schema

Type: object

Show Source

• chargeDestination: boolean
  The destination for a charge.
• chargeSource: boolean
  The source for a charge.
• description: string
  The transfer's description.
• extension: object extension
  The extended attributes.
• sourceLocation: object LocationDetails
• sourceRef: object SourceRef
  The balance transfer's source.
• targetLocation: object LocationDetails
• targetRef: object TargetRef
  The balance transfer's target.
• transferAmount(required): number
  The transfer amount.
• transferAmountType: integer (int32)
  The transfer amount's type.
• validFrom: string (date-time)
  The date and time the transfer's validity starts.
• validTo: string (date-time)
  The date and time the transfer's validity ends.

{
    "required":[
        "transferAmount"
    ],
    "type":"object",
    "properties":{
        "extension":{
            "type":"object",
            "description":"The extended attributes."
        },
        "sourceRef":{
            "$ref":"#/components/schemas/SourceRef"
        },
        "targetRef":{
            "$ref":"#/components/schemas/TargetRef"
        },
        "transferAmount":{
            "type":"number",
            "description":"The transfer amount."
        },
        "transferAmountType":{
            "type":"integer",
            "description":"The transfer amount's type.",
            "format":"int32"
        },
        "chargeSource":{
            "type":"boolean",
            "description":"The source for a charge."
        },
        "chargeDestination":{
            "type":"boolean",
            "description":"The destination for a charge."
        },
        "validFrom":{
            "type":"string",
            "description":"The date and time the transfer's validity starts.",
            "format":"date-time"
        },
        "validTo":{
            "type":"string",
            "description":"The date and time the transfer's validity ends.",
            "format":"date-time"
        },
        "description":{
            "type":"string",
            "description":"The transfer's description."
        },
        "sourceLocation":{
            "$ref":"#/components/schemas/LocationDetails"
        },
        "targetLocation":{
            "$ref":"#/components/schemas/LocationDetails"
        }
    },
    "xml":{
        "name":"transferBalance"
    }
}

Nested Schema : extension

Type: object

The extended attributes.

Nested Schema : LocationDetails

Type: object

Show Source

• locale(required): string
  A locale.
• zoneMapName(required): string
  The zonemap's name.
• zoneMapTarget(required): string
  The target zonemap.

{
    "required":[
        "locale",
        "zoneMapName",
        "zoneMapTarget"
    ],
    "type":"object",
    "properties":{
        "locale":{
            "type":"string",
            "description":"A locale."
        },
        "zoneMapTarget":{
            "type":"string",
            "description":"The target zonemap."
        },
        "zoneMapName":{
            "type":"string",
            "description":"The zonemap's name."
        }
    }
}

Nested Schema : SourceRef

Type: object

The balance transfer's source.

Show Source

• id(required): string
  The source's ID.
• type(required): string
  The source's type. Can be one of the following:

  • balanceGroup
  • account
  • service

{
    "required":[
        "id",
        "type"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The source's ID."
        },
        "type":{
            "type":"string",
            "description":"The source's type. Can be one of the following: <ul><li>balanceGroup</li><li>account</li><li>service</li></ul>"
        }
    },
    "description":"The balance transfer's source."
}

Nested Schema : TargetRef

Type: object

The balance transfer's target.

Show Source

• id(required): string
  The target's ID.
• type(required): string
  The target's type. Can be one of the following:

  • balanceGroup
  • account
  • service

{
    "required":[
        "id",
        "type"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The target's ID."
        },
        "type":{
            "type":"string",
            "description":"The target's type. Can be one of the following: <ul><li>balanceGroup</li><li>account</li><li>service</li></ul>"
        }
    },
    "description":"The balance transfer's target."
}

Request Body - application/json ()

The details of the balance transfer to create. The minimum required parameters are:

• sourceRef
• targetRef
• transferAmount

The source and target can be balance group IDs, account IDs, account numbers, service IDs, or service numbers/MSISDN numbers.

Root Schema : schema

Type: object

Show Source

• chargeDestination: boolean
  The destination for a charge.
• chargeSource: boolean
  The source for a charge.
• description: string
  The transfer's description.
• extension: object extension
  The extended attributes.
• sourceLocation: object LocationDetails
• sourceRef: object SourceRef
  The balance transfer's source.
• targetLocation: object LocationDetails
• targetRef: object TargetRef
  The balance transfer's target.
• transferAmount(required): number
  The transfer amount.
• transferAmountType: integer (int32)
  The transfer amount's type.
• validFrom: string (date-time)
  The date and time the transfer's validity starts.
• validTo: string (date-time)
  The date and time the transfer's validity ends.

{
    "required":[
        "transferAmount"
    ],
    "type":"object",
    "properties":{
        "extension":{
            "type":"object",
            "description":"The extended attributes."
        },
        "sourceRef":{
            "$ref":"#/components/schemas/SourceRef"
        },
        "targetRef":{
            "$ref":"#/components/schemas/TargetRef"
        },
        "transferAmount":{
            "type":"number",
            "description":"The transfer amount."
        },
        "transferAmountType":{
            "type":"integer",
            "description":"The transfer amount's type.",
            "format":"int32"
        },
        "chargeSource":{
            "type":"boolean",
            "description":"The source for a charge."
        },
        "chargeDestination":{
            "type":"boolean",
            "description":"The destination for a charge."
        },
        "validFrom":{
            "type":"string",
            "description":"The date and time the transfer's validity starts.",
            "format":"date-time"
        },
        "validTo":{
            "type":"string",
            "description":"The date and time the transfer's validity ends.",
            "format":"date-time"
        },
        "description":{
            "type":"string",
            "description":"The transfer's description."
        },
        "sourceLocation":{
            "$ref":"#/components/schemas/LocationDetails"
        },
        "targetLocation":{
            "$ref":"#/components/schemas/LocationDetails"
        }
    },
    "xml":{
        "name":"transferBalance"
    }
}

Nested Schema : extension

Type: object

The extended attributes.

Nested Schema : LocationDetails

Type: object

Show Source

• locale(required): string
  A locale.
• zoneMapName(required): string
  The zonemap's name.
• zoneMapTarget(required): string
  The target zonemap.

{
    "required":[
        "locale",
        "zoneMapName",
        "zoneMapTarget"
    ],
    "type":"object",
    "properties":{
        "locale":{
            "type":"string",
            "description":"A locale."
        },
        "zoneMapTarget":{
            "type":"string",
            "description":"The target zonemap."
        },
        "zoneMapName":{
            "type":"string",
            "description":"The zonemap's name."
        }
    }
}

Nested Schema : SourceRef

Type: object

The balance transfer's source.

Show Source

• id(required): string
  The source's ID.
• type(required): string
  The source's type. Can be one of the following:

  • balanceGroup
  • account
  • service

{
    "required":[
        "id",
        "type"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The source's ID."
        },
        "type":{
            "type":"string",
            "description":"The source's type. Can be one of the following: <ul><li>balanceGroup</li><li>account</li><li>service</li></ul>"
        }
    },
    "description":"The balance transfer's source."
}

Nested Schema : TargetRef

Type: object

The balance transfer's target.

Show Source

• id(required): string
  The target's ID.
• type(required): string
  The target's type. Can be one of the following:

  • balanceGroup
  • account
  • service

{
    "required":[
        "id",
        "type"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The target's ID."
        },
        "type":{
            "type":"string",
            "description":"The target's type. Can be one of the following: <ul><li>balanceGroup</li><li>account</li><li>service</li></ul>"
        }
    },
    "description":"The balance transfer's target."
}

Back to Top

Response

201 Response

The balance was created succesfully.

400 Response

The request isn't valid.

500 Response

An internal server error occurred.

Back to Top

Examples

This example shows how to transfer a balance by submitting a POST request on the REST resource using cURL. For more information about cURL, see "Use cURL".

cURL Command

curl -X POST 'http://hostname:port/bcws/webresources/version/billunits/balancegroups/transferbalance' -H 'content-type: application/json' -d @balanceTransfer.json

where:

• hostname is the URL for the Billing Care REST server.
• port is the port for the Billing Care REST server.
• version is the version of the API you're using, such as v1.0.
• balanceTransfer.json is the JSON file that specifies the balance to transfer.

Example of Request Body

This example shows the contents of the balanceTransfer.json file sent as the request body.

{
   "description":"Balance transfer",
   "sourceRef":{
      "id":"90989098",
      "type":"service"
   },
   "targetRef":{
      "id":"89878987",
      "type":"service"
   },
   "transferAmount":10,
   "transferAmountType":1000095,
   "validFrom":"2021-09-21T13:14:53",
   "validTo":"2023-12-21T13:14:53",
   "chargeSource":"true",
   "chargeDestination":"true",
   "sourceLocation":{
      "locale":"Bangalore;Karnataka;560076;IN"
   },
   "targetLocation":{
      "locale":"Bangalore;Karnataka;560076;BT"
   }
}

Example of Response Body

This example shows the contents of the response body in JSON format.

{
    "extension": null,
    "id": "0.0.0.1+-event-audit-transfer_balance+3355",
    "uri": "http://host:port/bcws/webresources/v1.0/billunits/balancegroups/transferbalance/0.0.0.1+-event-audit-transfer_balance+3355",
    "transferAmount": 10,
    "transferAmountType": 1000095,
    "sourceRef": {
        "id": "90989098",
        "type": "service"
    },
    "targetRef": {
        "id": "89878987",
        "type": "service"
    },
    "sourceBucket": [
        {
            "validFrom": 1647993600000,
            "validTo": 0,
            "currentBalance": -2760.0
        }
    ],
    "targetBucket": [
        {
            "validFrom": 1647993600000,
            "validTo": 0,
            "currentBalance": -4390
        },
        {
            "validFrom": 1632230093000,
            "validTo": 1703164493000,
            "currentBalance": -50.0
        }
    ],
    "sourceTransferFee": {
        "amount": 3.00,
        "feeTax": 0.21,
        "resourceId": 840
    },
    "targetTransferFee": {
        "amount": 3.00,
        "feeTax": 0.15,
        "resourceId": 840
    }
}

Back to Top