Accounts

Get account information

Returns all the info about a single account given by account id.

GET /orgs/{org_id}/accounts/{account_id}

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000 \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	GetAccount
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
405	Method Not Allowed	Method not allowed	None
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Update account payment method

Update account payment method for a given account id

PATCH /orgs/{org_id}/accounts/{account_id}/payment-method

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier
body	body	PatchAccountPaymentMethod	true	‘none’

Request body - instance of PatchAccountPaymentMethod

1
2
3
4
5
6


{
  "type": "BANK_TRANSFER",
  "details": {
    "iban": "ES7921000813610123456789"
  }
}

Name	Type	Required	Description
type	PatchPaymentType	true	none
details	PatchAccountPaymentMethodDetails	false	iban is mandatory when type is DIRECT_DEBIT, token_id OR reference_id is mandatory when type is CREDIT_CARD

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12



curl -X PATCH https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/payment-method \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY" \
 --data-raw "{
  'type': 'BANK_TRANSFER',
  'details': {
    'iban': 'ES7921000813610123456789'
  }
}" 

Responses

Code	Meaning	Description	Schema
202	Accepted	Asynchronous payment method update accepted (credit card with reference_id for pending tokenization)	None
204	No Content	Synchronous payment method update completed successfully (bank transfer, direct debit, or credit card with token_id)	None
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get account payment methods history

Returns the history of payment methods for a single account given by account id. The result includes all historical payment methods with their details.

GET /orgs/{org_id}/accounts/{account_id}/payment-methods/historical

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/payment-methods/historical \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	PaymentMethodHistoryResponse
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
405	Method Not Allowed	Method not allowed	None
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get account billing address history

Returns the history of billing address changed about a single account given by account id. You can filter the time period you want to query. To do this, you must enter the **'from'** and **'to'* query parameters. Neither field is required for the query. If you do not enter these fields, the entire billing address change history for the account will be displayed. If you enter these fields, they must be entered in the **yyyy-MM-dd** format.

GET /orgs/{org_id}/accounts/{account_id}/billing-address

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier
from	query	string(date)	false	start date query against createStamp column, with format yyyy-mm-dd, for example 2020-01-01
to	query	string(date)	false	end date query against createStamp column with format yyyy-mm-dd, for example 2020-01-01

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/billing-address?from='2020-01-01'&to='2020-12-31' \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	BillingAddressHistoryResponse
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
405	Method Not Allowed	Method not allowed	None
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get account invoice address information

Returns the invoice address information about a single account given by account id.

GET /orgs/{org_id}/accounts/{account_id}/invoice-recipient

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/invoice-recipient \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	InvoiceAddressResponse
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
405	Method Not Allowed	Method not allowed	None
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Add promotion to account

Add promotion for a given account id

POST /orgs/{org_id}/accounts/{account_id}/promotions

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier

Request example

1
2
3
4
5



curl -X POST https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/promotions \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	[AccountPromotion]
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

get account promotions

list account promotions by account
ACTIVATED: Returns the list of active promotions for the account. Those with a past activated_date and future expiration_date, which must be applied to the customer's invoice. This is the default value if not sent.
SCHEDULED: Returns the list of scheduled promotions: those with a future activation date.
ALL: includes all those mentioned in the previous two.

GET /orgs/{org_id}/accounts/{account_id}/promotions

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier
account_promotion_type	query	string	false	Account Promotion Type

Enumerated Values

Property	Values
account_promotion_type	one of [ACTIVE, SCHEDULED, ALL]

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/promotions?account_promotion_type='ACTIVE' \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	[AccountPromotion]
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

get promotion history to accounts

get all operation to promotions to account by date

GET /orgs/{org_id}/accounts/{account_id}/promotions_hist

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier
start_date	query	string(date)	false	Reference date to list account promotion operation history

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/promotions_hist?start_date='2025-09-01' \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	[AccountPromotionHistory]
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Update promotion account

Update cancellation date to account promotion

PATCH /orgs/{org_id}/accounts/{account_id}/promotions/{account_promotion_id}

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
account_id	path	string(uuid)	true	Account identifier
account_promotion_id	path	string(uuid)	true	Account promotion relation identifier
body	body	PatchAccountPromotion	true	‘none’

Request body - instance of PatchAccountPromotion

1
2
3


{
  "cancellation_date": "2025-09-01"
}

Name	Type	Required	Description
cancellation_date	string(date)	true	Cancellation Date to promotion in account

Request example

1
2
3
4
5
6
7
8
9



curl -X PATCH https://customers.sta.masstack.com/v4/orgs/telco/accounts/123e4567-e89b-12d3-a456-556642440000/promotions/123e4567-e89b-12d3-a456-556642440000 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY" \
 --data-raw "{
  'cancellation_date': '2025-09-01'
}" 

Responses

Code	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get the account ID list

Get the account ID list for a single customer

GET /orgs/{org_id}/customers/{customer_id}/accounts

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000/accounts \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	Customer accounts returned successfully	AccountIds
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Post account information

Create account information about a single account and a single customer

POST /orgs/{org_id}/customers/{customer_id}/accounts

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier
body	body	PostAccount	true	‘none’

Request body - instance of PostAccount

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


{
  "modality": "RECURRING_PREPAID",
  "billing_address": {
    "address_lines": [
      "Avenida de Bruselas, 38"
    ],
    "postal_code": "28108",
    "state_id": "28",
    "locality": "Alcobendas",
    "administrative_area": "Madrid",
    "region_code": "ES"
  },
  "payment_method": {
    "type": "BANK_TRANSFER",
    "details": {
      "iban": "ES7921000813610123456789"
    }
  }
}

Name	Type	Required	Description
modality	string	true	none
billing_address	BillingAddress	false	none
payment_method	PaymentMethod	true	none

Property	Values
modality	one of [RECURRING_PREPAID, POSTPAID]

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25



curl -X POST https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000/accounts \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY" \
 --data-raw "{
  'modality': 'RECURRING_PREPAID',
  'billing_address': {
    'address_lines': [
      'Avenida de Bruselas, 38'
    ],
    'postal_code': '28108',
    'state_id': '28',
    'locality': 'Alcobendas',
    'administrative_area': 'Madrid',
    'region_code': 'ES'
  },
  'payment_method': {
    'type': 'BANK_TRANSFER',
    'details': {
      'iban': 'ES7921000813610123456789'
    }
  }
}" 

Responses

Code	Meaning	Description	Schema
200	OK	Synchronous workflow completed successfully (bank transfer, direct debit, or credit card with token_id)	AccountCreated
202	Accepted	Asynchronous workflow accepted (credit card with reference_id for pending tokenization)	AccountCreated
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
409	Conflict	Conflict	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Delete account information

Delete account information about a single account and a single customer given by the ids.

DELETE /orgs/{org_id}/customers/{customer_id}/accounts/{account_id}

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier
account_id	path	string(uuid)	true	Account identifier

Request example

1
2
3
4
5



curl -X DELETE https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000/accounts/123e4567-e89b-12d3-a456-556642440000 \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
409	Conflict	Conflict	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get available payment methods for an account

Returns all available payment methods for an account

GET /orgs/{org_id}/customers/{customer_id}/accounts/{account_id}/available-payment-methods

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier
account_id	path	string(uuid)	true	Account identifier

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000/accounts/123e4567-e89b-12d3-a456-556642440000/available-payment-methods \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	Payment methods returned successfully	AvailablePaymentMethods
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse