API reference

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.

#List program categories

POST/API/v4/Programs/ProgramCategory

Returns 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

  • GetProgramCategoryobjectRequired

    Wrapper object for the ProgramCategory request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • PaginationobjectRequired

        Controls which page of results is returned.

        Child parameters2
        • RecordsToSkipstringRequired

          The page number to return, starting at "1". Integer as a string, e.g. "2" for the second page.

        • RecordsToTakestringRequired

          The maximum number of results to return per page. Integer as a string, e.g. "25".

Response fields

  • GetProgramCategoryResponseobject

    Response wrapper.

    Child parameters1
    • ProgramCategoryResultobject

      Result of the operation.

      Child parameters3
      • ProgramCategoryobject

        Container for the program categories.

        Child parameters1
        • ProgramCategoryDetailsobject[]

          The program categories.

          Child parameters2
          • CategoryIDinteger

            The unique internal identifier code for the program category.

          • CategoryNamestring

            A readable display name for the program category, for example Performance.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether 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 with Success.

      • PaginationTotalobject

        Pagination details for the returned results.

        Child parameters3
        • RecordsToSkipinteger

          The page number of these results, as sent in the request.

        • RecordsToTakeinteger

          The maximum number of results requested per page.

        • RecordsTotalinteger

          The 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

POST/API/v4/Programs/ProgramType

Returns 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

  • GetProgramTypeobjectRequired

    Wrapper object for the ProgramType request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters3
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • CategoryIDstringRequired

        The unique internal identifier code for the program category. Integer as a string, e.g. "2".

      • PaginationobjectRequired

        Controls which page of results is returned.

        Child parameters2
        • RecordsToSkipstringRequired

          The page number to return, starting at "1". Integer as a string, e.g. "2" for the second page.

        • RecordsToTakestringRequired

          The maximum number of results to return per page. Integer as a string, e.g. "25".

Response fields

  • GetProgramTypeResponseobject

    Response wrapper.

    Child parameters1
    • ProgramTypeResultobject

      Result of the operation.

      Child parameters3
      • ProgramTypeobject

        Container for the program types.

        Child parameters1
        • ProgramTypeDetailobject[]

          The program types (subcategories) in the requested category.

          Child parameters2
          • SubCategoryIDinteger

            The unique internal identifier code for the program subcategory.

          • SubCategoryNamestring

            A readable display name for the program subcategory, for example Bonus.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether 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 with Success.

      • PaginationTotalobject

        Pagination details for the returned results.

        Child parameters3
        • RecordsToSkipinteger

          The page number of these results, as sent in the request.

        • RecordsToTakeinteger

          The maximum number of results requested per page.

        • RecordsTotalinteger

          The total number of records available for this query.

Related: List program categories · Create a payment program · Update a payment program

#Create a payment program

POST/API/v4/Programs/CreateProgram

Creates 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

  • CreateProgramobjectRequired

    Wrapper object for the CreateProgram request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters7
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • DescriptionstringRequired

        A readable name or short description of the payment program, for example "Q3 Employee Bonus Program".

      • TransactionCategoryIDstringRequired

        The top-level numeric ID for the transaction category. Integer as a string, e.g. "2".

      • TransactionSubCategoryIDstringRequired

        The specific numeric ID for the transaction sub-category. Integer as a string, e.g. "4".

      • IsClaimstringRequired

        Send "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 JSON true as "True" and saves the program as not a claim, with no error. With "true", ClaimAmount (for example "341.25") and CurrencyCode (for example "USD") are required. With "false", Xtrm ignores them. Leaving IsClaim out, or sending "", fails with 400 and IsClaim is Mandatory.

      • ClaimAmountstringOptional

        The amount of the claim, as a decimal string of 0 or more with at most 2 decimals, for example "341.25". Required when IsClaim is "true"; Xtrm ignores it when IsClaim is "false".

      • CurrencyCodestringOptional

        The three-letter ISO 4217 code of the currency of ClaimAmount, for example USD. Required when IsClaim is "true"; Xtrm ignores it when IsClaim is "false".

Response fields

  • CreateProgramsResponseobject

    Response wrapper.

    Child parameters1
    • CreateProgramsResultobject

      Result of the operation.

      Child parameters2
      • ProgramIDstring

        The unique internal identifier generated for the newly created payment program. Returned as a string, e.g. "1026".

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List program categories · List program types for a category · List your company's programs · Update a payment program

#Update a payment program

POST/API/v4/Programs/UpdateProgram

Updates 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.

Tip

To look up the ProgramID of an existing program, call GetPrograms, which returns it as ProgramId.

Body parameters

  • UpdateProgramobjectRequired

    Wrapper object for the UpdateProgram request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters8
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • DescriptionstringRequired

        A readable name or short description of the payment program, for example "Updated Q3 Employee Bonus Program".

      • TransactionCategoryIDstringRequired

        The top-level numeric ID for the transaction category. Integer as a string, e.g. "2".

      • TransactionSubCategoryIDstringRequired

        The specific numeric ID for the transaction sub-category. Integer as a string, e.g. "4".

      • IsClaimstringRequired

        Send "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 JSON true as "True" and saves the program as not a claim, with no error. With "true", ClaimAmount (for example "341.25") and CurrencyCode (for example "USD") are required. With "false", Xtrm ignores them. Leaving IsClaim out, or sending "", fails with 400 and IsClaim is Mandatory.

      • ClaimAmountstringOptional

        The amount of the claim, as a decimal string of 0 or more with at most 2 decimals, for example "341.25". Required when IsClaim is "true"; Xtrm ignores it when IsClaim is "false".

      • CurrencyCodestringOptional

        The three-letter ISO 4217 code of the currency of ClaimAmount, for example USD. Required when IsClaim is "true"; Xtrm ignores it when IsClaim is "false".

      • ProgramIDstringRequired

        The unique internal identifier for the program you are updating. Integer as a string, e.g. "1026".

Response fields

  • UpdateProgramsResponseobject

    Response wrapper.

    Child parameters1
    • UpdateProgramsResultobject

      Result of the operation.

      Child parameters2
      • ProgramIDstring

        The unique internal identifier for the updated payment program. Returned as a string, e.g. "1026".

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List your company's programs · Create a payment program · List program categories · List program types for a category

#List your company's programs

POST/API/v4/Programs/GetPrograms

Returns 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

  • GetProgramsobjectRequired

    Wrapper object for the GetPrograms request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • PaginationobjectRequired

        Controls which page of results is returned.

        Child parameters2
        • RecordsToSkipstringRequired

          The page number to return, starting at "1". Integer as a string, e.g. "2" for the second page.

        • RecordsToTakestringRequired

          The maximum number of results to return per page. Integer as a string, e.g. "25".

Response fields

  • GetProgramsResponseobject

    Response wrapper.

    Child parameters1
    • ProgramsResultobject

      Result of the operation.

      Child parameters3
      • Programsobject

        Container for the company's programs.

        Child parameters1
        • ProgramDetailsobject[]

          The company's payment programs.

          Child parameters5
          • ProgramIdinteger

            The unique internal identifier for the program.

          • ProgramNamestring

            The name or short description of the payment program, as you supplied it.

          • ProgramCategorystring

            The assigned category or sub-category classification for the program, for example Performance.

          • ProgramTypestring

            The operational type or classification of the payment program, for example Bonus.

          • IsClaimstring

            Whether this is a claimed reward program (compensation that the recipient requests): the string Y or N.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether 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 with Success.

      • PaginationTotalobject

        Pagination details for the returned results.

        Child parameters3
        • RecordsToSkipinteger

          The page number of these results, as sent in the request.

        • RecordsToTakeinteger

          The maximum number of results requested per page.

        • RecordsTotalinteger

          The 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