--- swagger: "2.0" info: description: The Pay with Points API lets Citi customers use their Citi Points to pay for all or part of a transaction on your app. To simplify integration, transaction payments are processed through your existing payment gateway. A matching statement credit is then applied to the customer's Citi account, usually within 1-3 days. title: Pay With Points version: 1.0.0a x-ibm-name: paywithpoints_100a basePath: /api schemes: - https x-ibm-configuration: enforced: true phase: realized testable: true tags: [] definitions: RewardsLinkageRequest: type: object required: - lastFourDigitsCardNumber - citiCardHolderPhoneNumber - merchantCustomerReferenceId properties: lastFourDigitsCardNumber: description: Last four digits of the card number type: string example: "7411" citiCardHolderPhoneNumber: description: Citi registered primary mobile number of the credit card holder type: string example: "2608191234" merchantCustomerReferenceId: description: Denotes the unique reference identifier which merchant has for a particular customer. type: string example: "2608191234111" RewardsLinkageResponse: properties: rewardLinkCode: description: Unique link code issued during registration process. This is to be used in all subsequent reward transactions type: string example: "9035268" ErrorResponse: properties: type: type: string enum: - error - warn - invalid - fatal description:
invalid - Request did not confirm to the specification and was unprocessed & rejected. Please fix the value and try again

warn - Request was partially processed. E.g. some of the fields are missing in response to the system issues, request was accepted successfully but will be processed asynchronously

error - The request was accepted but could not be processed successfully

fatal - There was an internal system error while processing the request. These are technical errors and will be resolved by Citi, and the consumer should retry after some time. Business errors will not be categorized as fatal
code: description: Error code which qualifies the error type: string details: description: Human readable explanation specific to the occurrence of the problem type: string location: description: The name of the field that resulted in the error type: string moreInfo: description: URI to human readable documentation of the error type: object required: - type - code RewardsLinkageActivationRequest: properties: linkageConfirmationCode: description: Confirmation number for reward link code activation. type: string example: "735937" required: - linkageConfirmationCode GetRewardPointBalanceResponse: properties: availablePointBalance: type: number format: int64 description: Number of rewards points or miles available. example: 10000 programConversionRate: description: Points to currency conversion rate for the rewards program type: number format: double example: 0.252100 currencyCode: description: The currency code of the account in ISO 4217 format type: string example: SGD maximumPointsToRedeem: description: The maximum number of points that can be used towards a purchase type: number format: int64 example: 10000 minimumPointsToRedeem: description: The minimum number of points that can be used towards a purchase type: number format: int64 example: 5000 required: - availablePointBalance RewardPointsRedemptionRequest: properties: transactionReferenceNumber: description: This is reference number for the original transaction done at merchant side using the card. type: string example: 132323454de6234543 redemptionOrder: $ref: '#/definitions/RedemptionOrder' required: - transactionReferenceNumber - redemptionOrder RedemptionOrder: properties: transactionAmount: description: 'The total transaction amount. If both transactionAmount and pointsToRedeem are sent, it should be correct combination as per the below programConversionRate logic: pointsToRedeem = RoundOf (transactionAmount/programConversionRate)' type: number format: double example: 100.500000 currencyCode: description: The currency code of the account in ISO 4217 format type: string example: AUD pointsToRedeem: description: The points or miles that needs to redeemed. If both transactionAmount and pointsToRedeem are sent, it should be correct combination as per the below programConversionRate logic:pointsToRedeem = RoundOf (transactionAmount/programConversionRate) type: number format: int64 example: 1005 transactionDescription: description: Transaction description from the merchant type: string example: Completed required: - transactionAmount RewardPointsRedemptionResponse: properties: orderId: description: The unique order id type: string example: T25100025 availablePointBalance: description: The new points or miles balance type: integer format: int64 example: 6000 required: - orderId securityDefinitions: Client_id: type: apiKey name: X-IBM-Client-Id in: header description: "" paths: /v1/apac/rewards/linkage: post: summary: Enroll in Pay with Points description: Enrolls the customer into the Pay with Points program and returns a token, which requires activation and that will be used for subsequent API calls. Separate enrollment is required for each credit card. tags: [] parameters: - name: Authorization in: header description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' required: true type: string - name: uuid in: header description: 128 bit random UUID generated uniquely for every request. type: string required: true - name: Accept in: header description: Content-Type that are acceptable for the response. type: string required: true - name: Content-Type in: header description: application/json required: true type: string - name: Accept-Language in: header description: Accept-Language header. required: false type: string - name: client_id in: header description: The client ID you received during application registration in the developer portal type: string required: true - name: RewardsLinkageRequest in: body description: card information required: true schema: $ref: '#/definitions/RewardsLinkageRequest' responses: 200: description: Successful operation. schema: $ref: '#/definitions/RewardsLinkageResponse' 400: description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
error cardAlreadyRegisteredThe card is already registered
errorinvalidCardTypeCard type is invalid
schema: $ref: '#/definitions/ErrorResponse' 401: description:
errorunAuthorizedAuthorization credentials are missing or invalid
schema: $ref: '#/definitions/ErrorResponse' 403: description:
erroraccessNotConfiguredAccess is not configured for this resource
schema: $ref: '#/definitions/ErrorResponse' 500: description:
fatalserverUnavailableThe request failed due to an internal error/server unavailability
schema: $ref: '#/definitions/ErrorResponse' /v1/apac/rewards/{rewardLinkCode}/activations: put: summary: Token Activation description: Activate the Rewards Token associated with the last four digits of the credit card number provided and the phone number. tags: [] parameters: - name: uuid in: header description: 128 bit random UUID generated uniquely for every request. required: true type: string - name: Accept in: header description: Content-Type that are acceptable for the response. required: true type: string - name: client_id in: header description: Client ID generated during application registration. required: true type: string - name: Content-Type in: header description: application/json required: true type: string - name: Authorization in: header description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' required: true type: string - name: Accept-Language in: header description: Accept-Language header. required: false type: string - name: rewardLinkCode in: path description: Unique link code issued during registration process. required: true type: string - name: RewardsLinkageActivationRequest in: body required: true schema: $ref: '#/definitions/RewardsLinkageActivationRequest' responses: 200: description: Successful operation. 400: description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
erroractivationFailedLink code activation is failed
errorexceedsMaximumAttemptsMaximum attempts exceeded for activation. Link credit card to a merchant again.
errorlinkageConfirmationCodeExpiredLinkage confirmation code is expired. Link credit card to a merchant again
schema: $ref: '#/definitions/ErrorResponse' 401: description:
errorunAuthorizedAuthorization credentials are missing or invalid
schema: $ref: '#/definitions/ErrorResponse' 403: description:
erroraccessNotConfiguredAccess is not configured for this resource
schema: $ref: '#/definitions/ErrorResponse' 500: description:
fatalserverUnavailableThe request failed due to an internal error
schema: $ref: '#/definitions/ErrorResponse' /v1/apac/rewards/{rewardLinkCode}/pointBalance: get: summary: Retrieve rewards balance description: Returns the Citi Rewards Points balance and the details for converting the specified token to a dollar amount. tags: [] parameters: - name: rewardLinkCode in: path description: Unique link code issued during registration process. This is to be used to identify reward transactions type: string required: true - name: Authorization in: header description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' required: true type: string - name: uuid in: header description: 128 bit random UUID generated uniquely for every request. type: string required: true - name: Accept in: header description: Content-Type that are acceptable for the response. type: string required: true - name: client_id in: header description: The client ID you received during application registration in the developer portal type: string required: true - name: Accept-Language in: header description: Accept-Language header. required: false type: string responses: 200: description: Successful operation. schema: $ref: '#/definitions/GetRewardPointBalanceResponse' 400: description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
errorinvalidRewardLinkCodeReward link code is invalid
invalidinactiveRewardLinkCodeReward link code is inactive
schema: $ref: '#/definitions/ErrorResponse' 401: description:
errorunAuthorizedAuthorization credentials are missing or invalid
schema: $ref: '#/definitions/ErrorResponse' 403: description:
erroraccessNotConfiguredAccess is not configured for this resource
schema: $ref: '#/definitions/ErrorResponse' 404: description:
errorresourceNotFoundEmpty resource/resource not found
schema: $ref: '#/definitions/ErrorResponse' 500: description:
fatalserverUnavailableThe request failed due to an internal error/server unavailability
schema: $ref: '#/definitions/ErrorResponse' /v1/apac/rewards/{rewardLinkCode}/redemption: post: summary: Submit redemption request description: Submits a points redemption request for the credit card associated with the specified token. Redemptions are processed as statement credits to the Citi customer's account. tags: [] parameters: - name: rewardLinkCode in: path description: Unique link code per card associated with a member account type: string required: true - name: Authorization in: header description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' required: true type: string - name: uuid in: header description: 128 bit random UUID generated uniquely for every request. type: string required: true - name: Accept in: header description: Content-Type that are acceptable for the response. type: string required: true - name: Content-Type in: header description: application/json required: true type: string - name: client_id in: header description: The client ID you received during application registration in the developer portal type: string required: true - name: Accept-Language in: header description: Accept-Language header. required: false type: string - name: rewardsPointsRedemptionRequest in: body description: Redemption information required: true schema: $ref: '#/definitions/RewardPointsRedemptionRequest' responses: 200: description: Successful operation. schema: $ref: '#/definitions/RewardPointsRedemptionResponse' 400: description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
errorinvalidRewardLinkCodeReward link code is invalid
errorerrorGeneratingOrderIdOrder Id is not generated
errorinSufficientPointBalanceThe order points cannot be more than available balance of the member
errorexceedsMaximumPointsAllowedRequested amount or points are more than allowed equivalent points.
errornotEligibleToRedeemMember not eligible to order this item
errorbelowMinimumPointsAllowedRequested amount or points are less than allowed equivalent points.
errorinactiveRewardLinkCodeReward link code is inactive
errorinvalidPointsAndAmountCombinationPoints and amount combination are invalid
errorcurrencyNotSupportedCurrency is not supported
schema: $ref: '#/definitions/ErrorResponse' 401: description:
errorunAuthorizedAuthorization credentials are missing or invalid
schema: $ref: '#/definitions/ErrorResponse' 403: description:
erroraccessNotConfiguredAccess is not configured for this resource
schema: $ref: '#/definitions/ErrorResponse' 500: description:
fatalserverUnavailableThe request failed due to an internal error/server unavailability
schema: $ref: '#/definitions/ErrorResponse' security: - Client_id: [] consumes: - application/json produces: - application/json x-ibm-endpoints: - endpointUrl: https://sandbox.apihub.citi.com/gcb description: Custom Gateway API Endpoint type: - production - development ...