{ "openapi": "3.1.0", "info": { "title": "Client Management API", "description": "RAI Partners Client Management API", "license": { "name": "Proprietary — © RAI Partners Inc. All rights reserved.", "url": "https://www.raipartners.com" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.raipartners.com/client-management", "description": "Production" }, { "url": "https://api.dev.raipartners.com/client-management", "description": "Sandbox" } ], "tags": [ { "name": "Account", "description": "Account functions" }, { "name": "Authentication", "description": "Authentication functions" } ], "paths": { "/accounts": { "get": { "tags": [ "Account" ], "summary": "Retrieve the accounts", "description": "Retrieve the accounts associated with the client.", "operationId": "streamAccounts", "parameters": [ { "name": "API-Version", "in": "header", "schema": { "type": "string", "enum": [ "1.0.0" ] } } ], "responses": { "200": { "description": "Successful stream of accounts. IMPORTANT: The accounts are returned in NDJSON format (one account json object per line), not as an array.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/AccountInformation" } } } }, "400": { "description": "Bad request.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Generic invalid data": { "description": "Generic invalid data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:invalid-data", "title": "Bad Request", "status": 400, "detail": "One or more fields are invalid." } }, "Generic missing data": { "description": "Generic missing data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:missing-data", "title": "Bad Request", "status": 400, "detail": "One or more required fields are missing." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Unauthorized": { "description": "Unauthorized", "value": { "type": "urn:raipartners:api:clientmanagement:errors:authorization:unauthorized", "title": "Unauthorized", "status": 401, "detail": "You are not authorized to perform this action." } } } } } }, "403": { "description": "Forbidden.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Forbidden": { "description": "Forbidden", "value": { "type": "urn:raipartners:api:clientmanagement:errors:authorization:forbidden", "title": "Forbidden", "status": 403, "detail": "You are forbidden to perform this action." } } } } } }, "404": { "description": "not found.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Not found": { "description": "Not found", "value": { "type": "urn:raipartners:api:clientmanagement:errors:not-found", "title": "Not Found", "status": 404, "detail": "Resource not found." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Internal server error": { "description": "Internal server error", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred." } } } } } }, "503": { "description": "Service unavailable.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Service unavailable": { "description": "Service unavailable", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Service unavailable Error", "status": 503, "detail": "Service is unavailable." } } } } } } }, "security": [ { "bearer-jwt": [] } ] } }, "/auth/client-secret/rotation": { "post": { "tags": [ "Authentication" ], "summary": "Rotate the client secret", "description": "Rotate and return the client secret", "operationId": "rotateClientSecret", "parameters": [ { "name": "API-Version", "in": "header", "schema": { "type": "string", "enum": [ "1.0.0" ] } } ], "responses": { "200": { "description": "The rotated secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedSecret" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Generic invalid data": { "description": "Generic invalid data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:invalid-data", "title": "Bad Request", "status": 400, "detail": "One or more fields are invalid." } }, "Generic missing data": { "description": "Generic missing data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:missing-data", "title": "Bad Request", "status": 400, "detail": "One or more required fields are missing." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Unauthorized": { "description": "Unauthorized", "value": { "type": "urn:raipartners:api:clientmanagement:errors:authorization:unauthorized", "title": "Unauthorized", "status": 401, "detail": "You are not authorized to perform this action." } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Forbidden": { "description": "Forbidden", "value": { "type": "urn:raipartners:api:clientmanagement:errors:authorization:forbidden", "title": "Forbidden", "status": 403, "detail": "You are forbidden to perform this action." } } } } } }, "404": { "description": "not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Not found": { "description": "Not found", "value": { "type": "urn:raipartners:api:clientmanagement:errors:not-found", "title": "Not Found", "status": 404, "detail": "Resource not found." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Internal server error": { "description": "Internal server error", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred." } } } } } }, "503": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Service unavailable": { "description": "Service unavailable", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Service unavailable Error", "status": 503, "detail": "Service is unavailable." } } } } } } }, "security": [ { "bearer-jwt": [] } ] } }, "/auth/token": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate client", "description": "Authenticate a client and retrieve the JWT token", "operationId": "authenticateClient", "parameters": [ { "name": "API-Version", "in": "header", "schema": { "type": "string", "enum": [ "1.0.0" ] } } ], "requestBody": { "description": "The client credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "The JWT token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWTClientTokenResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Generic invalid data": { "description": "Generic invalid data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:invalid-data", "title": "Bad Request", "status": 400, "detail": "One or more fields are invalid." } }, "Generic missing data": { "description": "Generic missing data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:missing-data", "title": "Bad Request", "status": 400, "detail": "One or more required fields are missing." } } } } } }, "404": { "description": "not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Not found": { "description": "Not found", "value": { "type": "urn:raipartners:api:clientmanagement:errors:not-found", "title": "Not Found", "status": 404, "detail": "Resource not found." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Internal server error": { "description": "Internal server error", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred." } } } } } }, "503": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Service unavailable": { "description": "Service unavailable", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Service unavailable Error", "status": 503, "detail": "Service is unavailable." } } } } } } }, "security": [] } }, "/transactions/{date}": { "get": { "tags": [ "Account" ], "summary": "Retrieve the transactions", "description": "Retrieve the transactions across all accounts for the given cycle date.", "operationId": "streamTransactions", "parameters": [ { "name": "date", "in": "path", "description": "The cycle date for which the transactions are requested", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-07-31" }, { "name": "API-Version", "in": "header", "schema": { "type": "string", "enum": [ "1.0.0" ] } } ], "responses": { "200": { "description": "Successful stream of transactions. IMPORTANT: The transactions are returned in NDJSON format (one transaction json object per line), not as an array.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Bad request.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Generic invalid data": { "description": "Generic invalid data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:invalid-data", "title": "Bad Request", "status": 400, "detail": "One or more fields are invalid." } }, "Generic missing data": { "description": "Generic missing data", "value": { "type": "urn:raipartners:api:clientmanagement:errors:validation:missing-data", "title": "Bad Request", "status": 400, "detail": "One or more required fields are missing." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Unauthorized": { "description": "Unauthorized", "value": { "type": "urn:raipartners:api:clientmanagement:errors:authorization:unauthorized", "title": "Unauthorized", "status": 401, "detail": "You are not authorized to perform this action." } } } } } }, "403": { "description": "Forbidden.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Forbidden": { "description": "Forbidden", "value": { "type": "urn:raipartners:api:clientmanagement:errors:authorization:forbidden", "title": "Forbidden", "status": 403, "detail": "You are forbidden to perform this action." } } } } } }, "404": { "description": "not found.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Not found": { "description": "Not found", "value": { "type": "urn:raipartners:api:clientmanagement:errors:not-found", "title": "Not Found", "status": 404, "detail": "Resource not found." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Internal server error": { "description": "Internal server error", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred." } } } } } }, "503": { "description": "Service unavailable.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "Service unavailable": { "description": "Service unavailable", "value": { "type": "urn:raipartners:api:clientmanagement:errors:internal", "title": "Service unavailable Error", "status": 503, "detail": "Service is unavailable." } } } } } } }, "security": [ { "bearer-jwt": [] } ] } } }, "components": { "schemas": { "AccountIdentification": { "type": "object", "properties": { "id": { "type": "string", "description": "The 64 characters account identifier.", "example": "f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2", "pattern": "[0-9a-f]{64}" }, "number": { "type": "string", "description": "The 16 digit account number.", "example": "1234567890123456", "pattern": "\\d{16}" } }, "required": [ "id", "number" ] }, "AccountInformation": { "type": "object", "properties": { "accountIdentification": { "$ref": "#/components/schemas/AccountIdentification", "description": "The account identification." }, "status": { "type": "string", "description": "The account status.", "enum": [ "AuthorizationProhibited", "Bankrupt", "ChargeOff", "Closed", "Frozen", "InterestAccrualProhibited", "Lost", "Normal", "Revoked", "Stolen" ], "example": "Normal" }, "internalStatus": { "type": "string", "description": "The account internal status.", "enum": [ "CreditBalance", "Delinquent", "DelinquentAndOverLimit", "Normal", "OverLimit" ], "example": "Delinquent" }, "currentBalance": { "type": "number", "description": "The account current balance.", "example": 1000 }, "creditLimit": { "type": "number", "description": "The account credit limit.", "example": 10000 }, "annualRates": { "$ref": "#/components/schemas/Rates", "description": "The account annual rates." }, "openingDate": { "type": "string", "format": "date", "description": "The account opening date.", "example": "2022-01-31" }, "paymentDueDate": { "type": [ "string", "null" ], "format": "date", "description": "The account payment due date.", "example": "2022-02-01" }, "nextCycleDate": { "type": "string", "format": "date", "description": "The account next cycle date.", "example": "2022-03-01" }, "cycleToDatePaymentPosted": { "type": "number", "description": "The account cycle to date payment amount posted.", "example": 1000 }, "lastStatementPaymentAmount": { "type": "number", "description": "The account last statement payment amount.", "example": 1000 }, "primaryCardholder": { "$ref": "#/components/schemas/Individual", "description": "The account primary cardholder." }, "secondaryCardholder": { "oneOf": [ { "$ref": "#/components/schemas/Individual" }, { "type": "null" } ] } }, "required": [ "accountIdentification", "annualRates", "creditLimit", "currentBalance", "cycleToDatePaymentPosted", "internalStatus", "lastStatementPaymentAmount", "nextCycleDate", "openingDate", "primaryCardholder", "status" ] }, "Individual": { "type": "object", "properties": { "ssnId": { "type": "string", "description": "The individual social security number identifier.", "example": "b2ce1ee6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2", "pattern": "[0-9a-f]{64}" }, "ssn": { "type": "string", "description": "The 9 digit social security number.", "example": "123456789", "pattern": "\\d{9}" }, "name": { "type": "string", "description": "The individual name.", "example": "Doe, John", "maxLength": 50, "minLength": 5 }, "dob": { "type": "string", "format": "date", "description": "The individual date of birth.", "example": "1970-01-01" } }, "required": [ "dob", "name", "ssn", "ssnId" ] }, "Rates": { "type": "object", "properties": { "cash": { "type": "number", "description": "The cash rate in percent.", "example": 19.99 }, "merchandise": { "type": "number", "description": "The merchandise rate in percent.", "example": 12.99 } }, "required": [ "cash", "merchandise" ] }, "ProblemDetail": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "format": "uri", "description": "The URI of the problem type", "example": "urn:raipartners:api" }, "title": { "type": [ "string", "null" ], "description": "The title of the problem", "example": "Bad Request" }, "status": { "type": "integer", "format": "int32", "description": "The status code of the problem", "example": 400 }, "detail": { "type": [ "string", "null" ], "description": "The details of the problem", "example": "One or more required fields are missing." }, "instance": { "type": [ "string", "null" ], "format": "uri-reference", "description": "The instance of the problem", "example": "/account/12345/errors/abc-987" }, "properties": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "extra properties to enhance information about the problem" } }, "required": [ "status" ] }, "RotatedSecret": { "type": "object", "description": "Client rotated secret", "properties": { "secret": { "type": "string", "description": "The new client secret.", "example": "PX4eWb9rcRT1RBqvLw4GtuqyoUFWoGLr" } }, "required": [ "secret" ] }, "ClientTokenRequest": { "type": "object", "description": "A client token request payload", "properties": { "client_id": { "type": "string", "description": "The client ID to use for authentication", "example": "my-client-id" }, "client_secret": { "type": "string", "description": "The client secret to use for authentication", "example": "my-super-auth-secret" } }, "required": [ "client_id", "client_secret" ] }, "JWTClientTokenResponse": { "type": "object", "properties": { "scope": { "type": "string", "description": "The token scope as a space delimited set of values.", "example": "read:user write:user" }, "access_token": { "type": "string", "description": "The JWT token.", "example": "eyo....." }, "expires_in": { "type": "integer", "format": "int32", "description": "The token expiry in seconds.", "example": 300 }, "token_type": { "type": "string", "description": "The token type.", "example": "Bearer" }, "not-before-policy": { "type": "integer", "format": "int32", "description": "The not before policy in seconds.", "example": 0 }, "refresh_expires_in": { "type": "integer", "format": "int32", "description": "The refresh token expiry in seconds.", "example": 300 } }, "required": [ "access_token", "expires_in", "scope", "token_type" ] }, "CurrencyInfo": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO-3 Currency code", "example": "EUR", "pattern": "[A-Z]{3}" }, "name": { "type": "string", "description": "Currency name", "example": "Euro", "maxLength": 50 } }, "required": [ "code", "name" ] }, "ExchangeInfo": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/CurrencyInfo", "description": "Currency of the exchange" }, "amount": { "type": "number", "description": "Amount in foreign currency", "example": 24.2 }, "exchangeRate": { "type": [ "number", "null" ], "description": "Exchange rate from USD to foreign currency", "example": 1.171487603 } }, "required": [ "amount", "currency" ] }, "Merchant": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The optional merchant name.", "example": "MUSEO OPERA SANTA CROCE", "maxLength": 50 }, "category": { "type": [ "string", "null" ], "description": "The optional merchant category code (4 digit SIC).", "example": "7997", "pattern": "\\d{4}" }, "description": { "type": [ "string", "null" ], "description": "The optional merchant description.", "example": "MUSEO OPERA SANTA CROCE FIRENZE IT", "maxLength": 50 }, "location": { "oneOf": [ { "$ref": "#/components/schemas/MerchantLocation" }, { "type": "null" } ] } } }, "MerchantLocation": { "type": "object", "properties": { "city": { "type": [ "string", "null" ], "description": "The optional merchant city.", "example": "FIRENZE", "maxLength": 50 }, "state": { "type": [ "string", "null" ], "description": "The optional merchant state.", "example": "IT", "maxLength": 2 }, "country": { "type": [ "string", "null" ], "description": "The optional merchant country in ISO 3166-1 alpha-3 format.", "example": "ITA", "maxLength": 3 } } }, "Transaction": { "type": "object", "properties": { "referenceNumber": { "type": "string", "description": "The transaction reference number.", "example": "7434495GE9WRQ9QVE" }, "type": { "type": "string", "description": "The transaction type.", "enum": [ "Authorization", "AuthorizationAdjustment", "Sale", "CashAdvance", "Return", "MerchandiseSaleReversal", "CashAdvanceReversal", "ReturnReversal", "MerchandiseSaleAmountAdjustment", "CashAdvanceAmountAdjustment", "ReturnAmountAdjustment", "Payment", "PaymentReversal", "PaymentAmountAdjustment", "Adjustment", "CashAdvanceItemChargeRefund", "LatefeeRefund", "MerchandiseFinanceChargeRefund", "CashAdvanceFinanceChargeRefund", "BackdatedPaymentAdjustment", "MerchandiseItemChargeRefund", "OverLimitChargeRefund", "CreditInsuranceFeeRefund", "BackdateCashAdvanceandSalesAdjustment", "SmallBalanceChargeOff", "ChargeOffTotalAccount", "ChargeOffCashAdvanceInterest", "ChargeOffBilledLateCharges", "ChargeOffMerchandiseInterestandServiceCharge", "ChargeOffCreditInsurance", "ChargeOffAllFinanceCharges", "ChargeOffAllCurrentCashAdvanceInterest", "ChargeOffAllCurrentMerchandiseInterest", "ChargeOffCycleToDateLateCharges", "ChargeOffBilledCashAdvanceItemCharges", "ChargeOffBilledMerchandiseItemCharges", "ChargeOffBilledOverLimitFee", "ChargeOffCycleToDateCashAdvanceItemCharges", "ChargeOffCycleToDateMerchandiseItemCharges", "ChargeOffCycleToDateOverLimitFees", "AccountTransfer", "NotSpecified" ], "example": "Sale" }, "sys": { "type": "string", "description": "The 4 digit sys of the account.", "example": "6161", "pattern": "\\d{4}" }, "prin": { "type": "string", "description": "The 4 digit prin of the account.", "example": "0000", "pattern": "\\d{4}" }, "agent": { "type": "string", "description": "The 4 digit agent of the account.", "example": "1000", "pattern": "\\d{4}" }, "account": { "$ref": "#/components/schemas/AccountIdentification", "description": "The parent account associated with this transaction." }, "cardAccount": { "oneOf": [ { "$ref": "#/components/schemas/AccountIdentification" }, { "type": "null" } ] }, "amount": { "type": "number", "description": "The transaction amount in US Dollars.", "example": 28.35 }, "date": { "type": "string", "format": "date", "description": "The transaction date.", "example": "2023-01-01" }, "postedDate": { "type": "string", "format": "date", "description": "The date the transaction was posted.", "example": "2023-01-02" }, "cycleDate": { "type": "string", "format": "date", "description": "The cycle date assoicated with the transaction.", "example": "2023-01-02" }, "merchant": { "oneOf": [ { "$ref": "#/components/schemas/Merchant" }, { "type": "null" } ] }, "exchangeInfo": { "oneOf": [ { "$ref": "#/components/schemas/ExchangeInfo" }, { "type": "null" } ] } }, "required": [ "account", "agent", "amount", "cycleDate", "date", "postedDate", "prin", "referenceNumber", "sys", "type" ] } }, "securitySchemes": { "bearer-jwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }