Programs
Programs are your company's payment programs or projects, such as remittance, payment or budget programs. Each program has a name, a transaction category and sub-category, and an IsClaim flag that marks it as a claimed reward program (compensation that the recipient requests).
You create a program from a program category and a program type (subcategory). List the categories with ProgramCategory and the program types in a category with ProgramType. CreateProgram returns a ProgramID, which you pass to UpdateProgram to change the program. GetPrograms lists your company's programs.
To link a funding transaction to a program, pass the program's ID as ProgramID in FundWalletUsingBankTransfer.
- POST
/API/v4/Programs/ProgramCategoryList program categories - POST
/API/v4/Programs/ProgramTypeList program types for a category - POST
/API/v4/Programs/CreateProgramCreate a payment program - POST
/API/v4/Programs/UpdateProgramUpdate a payment program - POST
/API/v4/Programs/GetProgramsList your company's programs
#List program categories
/API/v4/Programs/ProgramCategoryReturns a paginated list of program categories. You use a program category together with a program type to create a program.
Each category in ProgramCategoryDetails has a CategoryID and a display name in CategoryName. To list the program types (subcategories) in a category, pass its CategoryID to ProgramType.
Body parameters
GetProgramCategoryobjectRequiredWrapper object for the
ProgramCategoryrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.PaginationobjectRequiredControls which page of results is returned.
Child parameters2
RecordsToSkipstringRequiredThe page number to return, starting at
"1". Integer as a string, e.g."2"for the second page.RecordsToTakestringRequiredThe maximum number of results to return per page. Integer as a string, e.g.
"25".
Response fields
GetProgramCategoryResponseobjectResponse wrapper.
Child parameters1
ProgramCategoryResultobjectResult of the operation.
Child parameters3
ProgramCategoryobjectContainer for the program categories.
Child parameters1
ProgramCategoryDetailsobject[]The program categories.
Child parameters2
CategoryIDintegerThe unique internal identifier code for the program category.
CategoryNamestringA readable display name for the program category, for example
Performance.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
[""], an array holding one empty string, so decide withSuccess.
PaginationTotalobjectPagination details for the returned results.
Child parameters3
RecordsToSkipintegerThe page number of these results, as sent in the request.
RecordsToTakeintegerThe maximum number of results requested per page.
RecordsTotalintegerThe total number of records available for this query.
Related: List program types for a category · Create a payment program · Update a payment program
#List program types for a category
/API/v4/Programs/ProgramTypeReturns a paginated list of the program types (subcategories) available for a given program category. Pass the category's CategoryID, as returned by ProgramCategory.
Each program type in ProgramTypeDetail has a SubCategoryID and a display name in SubCategoryName.
Body parameters
GetProgramTypeobjectRequiredWrapper object for the
ProgramTyperequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.CategoryIDstringRequiredThe unique internal identifier code for the program category. Integer as a string, e.g.
"2".PaginationobjectRequiredControls which page of results is returned.
Child parameters2
RecordsToSkipstringRequiredThe page number to return, starting at
"1". Integer as a string, e.g."2"for the second page.RecordsToTakestringRequiredThe maximum number of results to return per page. Integer as a string, e.g.
"25".
Response fields
GetProgramTypeResponseobjectResponse wrapper.
Child parameters1
ProgramTypeResultobjectResult of the operation.
Child parameters3
ProgramTypeobjectContainer for the program types.
Child parameters1
ProgramTypeDetailobject[]The program types (subcategories) in the requested category.
Child parameters2
SubCategoryIDintegerThe unique internal identifier code for the program subcategory.
SubCategoryNamestringA readable display name for the program subcategory, for example
Bonus.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
[""], an array holding one empty string, so decide withSuccess.
PaginationTotalobjectPagination details for the returned results.
Child parameters3
RecordsToSkipintegerThe page number of these results, as sent in the request.
RecordsToTakeintegerThe maximum number of results requested per page.
RecordsTotalintegerThe total number of records available for this query.
Related: List program categories · Create a payment program · Update a payment program
#Create a payment program
/API/v4/Programs/CreateProgramCreates a payment program or project for your company. The response returns the ProgramID of the new program and whether the operation succeeded.
You create a program from a program category and a program type (subcategory). To list them, call ProgramCategory and ProgramType.
Note
Keep the returned ProgramID. UpdateProgram requires it to identify the program you are updating.
Body parameters
CreateProgramobjectRequiredWrapper object for the
CreateProgramrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters7
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.DescriptionstringRequiredA readable name or short description of the payment program, for example
"Q3 Employee Bonus Program".TransactionCategoryIDstringRequiredThe top-level numeric ID for the transaction category. Integer as a string, e.g.
"2".TransactionSubCategoryIDstringRequiredThe specific numeric ID for the transaction sub-category. Integer as a string, e.g.
"4".IsClaimstringRequiredSend
"true", lowercase and in quotes, to make this a claim program, or"false". Only the exact string"true"makes a claim program: Xtrm reads a JSONtrueas"True"and saves the program as not a claim, with no error. With"true",ClaimAmount(for example"341.25") andCurrencyCode(for example"USD") are required. With"false", Xtrm ignores them. LeavingIsClaimout, or sending"", fails with400andIsClaim is Mandatory.ClaimAmountstringOptionalThe amount of the claim, as a decimal string of
0or more with at most 2 decimals, for example"341.25". Required whenIsClaimis"true"; Xtrm ignores it whenIsClaimis"false".CurrencyCodestringOptionalThe three-letter ISO 4217 code of the currency of
ClaimAmount, for exampleUSD. Required whenIsClaimis"true"; Xtrm ignores it whenIsClaimis"false".
Response fields
CreateProgramsResponseobjectResponse wrapper.
Child parameters1
CreateProgramsResultobjectResult of the operation.
Child parameters2
ProgramIDstringThe unique internal identifier generated for the newly created payment program. Returned as a string, e.g.
"1026".OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: List program categories · List program types for a category · List your company's programs · Update a payment program
#Update a payment program
/API/v4/Programs/UpdateProgramUpdates one of your company's payment programs or projects, identified by ProgramID. The response returns the ProgramID of the updated program and whether the operation succeeded.
The request takes the same program fields as CreateProgram, plus the ProgramID of the program to update.
Note
Send Description, TransactionCategoryID, TransactionSubCategoryID, and IsClaim in every update request. They are required.
Important
An update that sends anything other than "true" in IsClaim turns a claim program into a regular program and clears its ClaimAmount and CurrencyCode.
Tip
To look up the ProgramID of an existing program, call GetPrograms, which returns it as ProgramId.
Body parameters
UpdateProgramobjectRequiredWrapper object for the
UpdateProgramrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters8
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.DescriptionstringRequiredA readable name or short description of the payment program, for example
"Updated Q3 Employee Bonus Program".TransactionCategoryIDstringRequiredThe top-level numeric ID for the transaction category. Integer as a string, e.g.
"2".TransactionSubCategoryIDstringRequiredThe specific numeric ID for the transaction sub-category. Integer as a string, e.g.
"4".IsClaimstringRequiredSend
"true", lowercase and in quotes, to make this a claim program, or"false". Only the exact string"true"makes a claim program: Xtrm reads a JSONtrueas"True"and saves the program as not a claim, with no error. With"true",ClaimAmount(for example"341.25") andCurrencyCode(for example"USD") are required. With"false", Xtrm ignores them. LeavingIsClaimout, or sending"", fails with400andIsClaim is Mandatory.ClaimAmountstringOptionalThe amount of the claim, as a decimal string of
0or more with at most 2 decimals, for example"341.25". Required whenIsClaimis"true"; Xtrm ignores it whenIsClaimis"false".CurrencyCodestringOptionalThe three-letter ISO 4217 code of the currency of
ClaimAmount, for exampleUSD. Required whenIsClaimis"true"; Xtrm ignores it whenIsClaimis"false".ProgramIDstringRequiredThe unique internal identifier for the program you are updating. Integer as a string, e.g.
"1026".
Response fields
UpdateProgramsResponseobjectResponse wrapper.
Child parameters1
UpdateProgramsResultobjectResult of the operation.
Child parameters2
ProgramIDstringThe unique internal identifier for the updated payment program. Returned as a string, e.g.
"1026".OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: List your company's programs · Create a payment program · List program categories · List program types for a category
#List your company's programs
/API/v4/Programs/GetProgramsReturns your company's payment programs or projects.
Each program in ProgramDetails includes its ProgramId, name, category and type, and whether it is a claimed reward program (compensation that the recipient requests). In the example, the category and type are returned as names (Performance, Bonus).
Control paging with RecordsToSkip and RecordsToTake in the Pagination object. PaginationTotal in the response reports the total number of records available in RecordsTotal.
Tip
To link a funding transaction to a program, pass the program's ID as ProgramID in FundWalletUsingBankTransfer.
Note
IsClaim is returned as Y or N, not as the "true" or "false" string that CreateProgram and UpdateProgram take.
Body parameters
GetProgramsobjectRequiredWrapper object for the
GetProgramsrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.PaginationobjectRequiredControls which page of results is returned.
Child parameters2
RecordsToSkipstringRequiredThe page number to return, starting at
"1". Integer as a string, e.g."2"for the second page.RecordsToTakestringRequiredThe maximum number of results to return per page. Integer as a string, e.g.
"25".
Response fields
GetProgramsResponseobjectResponse wrapper.
Child parameters1
ProgramsResultobjectResult of the operation.
Child parameters3
ProgramsobjectContainer for the company's programs.
Child parameters1
ProgramDetailsobject[]The company's payment programs.
Child parameters5
ProgramIdintegerThe unique internal identifier for the program.
ProgramNamestringThe name or short description of the payment program, as you supplied it.
ProgramCategorystringThe assigned category or sub-category classification for the program, for example
Performance.ProgramTypestringThe operational type or classification of the payment program, for example
Bonus.IsClaimstringWhether this is a claimed reward program (compensation that the recipient requests): the string
YorN.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
[""], an array holding one empty string, so decide withSuccess.
PaginationTotalobjectPagination details for the returned results.
Child parameters3
RecordsToSkipintegerThe page number of these results, as sent in the request.
RecordsToTakeintegerThe maximum number of results requested per page.
RecordsTotalintegerThe total number of records available for this query.
Related: Create a payment program · Update a payment program · Fund a wallet by bank transfer · List company wallet transactions