--- swagger: "2.0" info: description: The Cards API allows you to perform actions on the actual credit cards of the Citi Customer who authorized your app. title: Cards version: 1.0.0 x-ibm-name: cards_100 basePath: /api schemes: - https x-ibm-configuration: enforced: true phase: realized testable: true tags: [] definitions: PermanentCreditLimitIncrease: properties: cardId: description: Unique Id of the card in encrypted format. type: string example: 3255613852316f2b4d4d796c344e38756339654972776f663745446e6d4c32486f455a4165374a476858343d requestedCreditLimitAmount: format: double description: Customers preferred revised credit limit. This is the combined limit shared with all the existing credit cards of the customer type: number example: 10000.250000 required: - cardId - requestedCreditLimitAmount EmploymentDetails: properties: occupationCode: description: Occupation code. This is a reference data field. Please use /utilities/referenceData/{occupationCode} resource to get valid values of this field with descriptions. type: string example: CONSULTANT required: - occupationCode ConsentDetails: properties: consentType: description: Applicant's consent types. This is a reference data field. Please use /v1/apac/utilities/referenceData/{consentType} resource to get valid value of this field with description. type: string example: COUNTER_OFFER_CONSENT consentGivenFlag: description: 'Consent flag. Valid values: true and false' type: boolean example: true required: - consentGivenFlag - consentType CreditLimitIncreaseRequest: properties: permanentCreditLimitIncrease: $ref: '#/definitions/PermanentCreditLimitIncrease' temporaryCreditLimitIncrease: $ref: '#/definitions/TemporaryCreditLimitIncrease' Address: properties: countrySpecificAddress: $ref: '#/definitions/CountrySpecificAddress' city: description: Town/City type: string example: Sydney addressType: description: Type of the address. This is a reference data field. Please use /utilities/referenceData/{addressType} resource to get valid values of this field with descriptions. type: string example: PRIMARY_ADDRESS countryCode: description: ISO country code. This is a reference data field. Please use /v1/apac/utilities/referenceData/{country} resource to get valid value of this field with description. type: string example: AU postalCode: description: Postal/ZIP code type: string example: WA 6125 addressLine1: description: Address line 1 type: string example: Post Box 56 addressLine2: description: Address line 2. It is the unit number for Australia type: string example: 99 George Street addressLine3: description: Address line 3. type: string example: Broadway Avenue state: description: State.This is a reference data field. Please use /v1/apac/utilities/referenceData/{addressState} resource to get valid value of this field with description. type: string example: QUEENSLAND addressLine4: description: Address line 4. type: string example: Wandaloo ESP required: - addressType IdentificationDocumentDetails: properties: idIssueState: description: State from which identification document was issued.This is a reference data field. Please use /v1/apac/utilities/referenceData/{addressState} resource to get valid value of this field with description. You can use addressState field name as the referenceCode parameter to retrieve the values. type: string example: QUEENSLAND idType: description: Type of Identification document. This is a reference data field. Please use /v1/apac/utilities/referenceData/{idType} resource to get valid values of this field with descriptions type: string example: PASSPORT idIssueDate: format: date description: Issuance date of identification document in ISO 8601 date format YYYY-MM-DD type: string example: "2017-04-12" idExpiryDate: format: date description: Expiry date of identification document in ISO 8601 date format YYYY-MM-DD type: string example: "2027-04-11" idNumber: description: 'Unique identifier of identification document. Ex: Passport Number' type: string example: S42258011 idIssuePlace: description: Identification document issuance place type: string example: Brisbane idIssueCountry: description: Country of issuance. This is a reference data field. Please use /v1/apac/utilities/referenceData/{country} resource to get valid value of this field with description. You can use idIssueCountry field name as the referenceCode parameter to retrieve the values. type: string example: AU CardUsageRequest: properties: cvv: description: CVV number in encrypted format type: string example: 3255613852316f2b4d4d796c344e38756339654972776f66 CountrySpecificAddress: properties: streetName: description: Applicant's street Name type: string example: George street streetType: description: Applicant's street Type.This is a reference data field. Please use /utilities/referenceData/{streetType} resource to get valid values of this field with descriptions. type: string example: Avenue streetNumber: description: Applicant's street Number type: string example: "52" unitNumber: description: Applicant's unit Number type: string example: "99" required: - streetNumber - streetName - streetType Name: properties: surname: description: Surname/last name of the applicant type: string example: Smith givenName: description: Given/first name of the applicant type: string example: John middleName: description: Middle name of the applicant type: string example: Bill salutation: description: Salutation. This is a reference data field. Please use /v1/apac/utilities/referenceData/{salutation} resource to get valid value of this field with description. type: string example: Mr required: - givenName - surname - salutation Demographics: properties: nationality: description: Applicant's nationality. This is a reference data field. Please use /v1/apac/utilities/referenceData/{country} resource to get valid value of this field with description. type: string example: AU dateOfBirth: format: date description: Applicant's date of birth in ISO 8601 date format YYYY-MM-DD type: string example: 1980-01-02' required: - dateOfBirth - nationality Phone: properties: phoneType: description: The type of phone. Ex:OFFICE, HOME, MOBILE, PRIMARY_MOBILE, FAX. This is a reference data field. Please use /v1/apac/utilities/referenceData/{phoneType} resource to get valid value of this field with description. type: string example: PRIMARY_MOBILE_NUMBER areaCode: description: The area code of phone number type: string example: "02" extension: description: Extension of telephone number type: string example: "23" phoneNumber: description: Applicant's phone number type: string example: "64042321" phoneCountryCode: description: Country calling code. This is a reference data field. Please use /utilities/referenceData/{phoneCountryCode} resource to get valid values of this field with descriptions type: string example: 61 required: - phoneType - phoneCountryCode - phoneNumber OverseasCardUsageRequest: properties: ActivationRequest: $ref: '#/definitions/ActivationRequest' overseasCardUsageOption: description: Activation code for overseas card Usage. This is a reference data field. Please use /v1/apac/utilities/referenceData/{overseasCardUsageOption} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values type: string example: ACTIVATE required: - overseasCardUsageOption CardDetails: properties: cardId: description: The card id in encrypted format type: string example: 3255613852316f2b4d4d796c344e38756339654972776f663745446e6d4c32486f455a4165374a476858343d displayCardNumber: description: A masked card number that can be displayed to the customer. type: string example: XXXXXXXXXXXX4521 localCardActivationIndicator: description: The card activation indicator for local usage. This is a reference data field. Please use /v1/apac/utilities/referenceData/{localCardActivationIndicator} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. type: string example: ACTIVE overseasCardActivationIndicator: description: The card activation indicator for overseas usage. This is a reference data field. Please use /v1/apac/utilities/referenceData/{overseasCardActivationIndicator} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. type: string example: ACTIVE perpetualActivationFlag: description: Flag to specify whether the card is activated perpetually, till card expiration type: boolean example: true overseasCardActivationStartDate: format: date description: Card activation start date in ISO 8601 date format YYYY-MM-DD for overseas usage. type: string example: "2016-11-01" overseasCardActivationEndDate: format: date description: Card activation end date in ISO 8601 date format YYYY-MM-DD for overseas usage. For perpetual activation, value is card expiry date type: string example: "2016-12-05" currentCreditLimitAmount: format: double description: Current credit limit amount on the credit card type: number example: 3500.250000 maximumPermanentCreditLimitAmount: format: double description: Maximum permanent credit limit amount allowed on the credit card type: number example: 5000.250000 maximumTemporaryCreditLimitAmount: format: double description: Maximum temporary credit limit amount allowed on the credit card type: number example: 5000.250000 subCardType: description: Type of the card. Debit or Credit.This is a reference data field. Please use /v1/apac/utilities/referenceData/{subCardType} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. type: string example: DEBIT cardHolderType: description: Indicator to specify whether the card is primary or supplementary. This is a reference data field. Please use /v1/apac/utilities/referenceData/{cardHolderType} resource to get valid value of this field with description. type: string example: PRIMARY cardIssueReason: description: Specifies the reason for the card issuance. Applicable only for recently issued cards. This is a reference data field. Please use /v1/apac/utilities/referenceData/{cardIssueReason} resource to get valid value of this field with description. type: string example: NEWLY_ONBOARDED_CARD cardFunctionsAllowed: type: array items: $ref: '#/definitions/CardFunctionsAllowed' required: - cardId - localCardActivationIndicator - subCardType - currentCreditLimitAmount ActivationRequest: properties: overseasCardActivationEndDate: format: date description: Card activation end date in ISO 8601 date format YYYY-MM-DD for overseas usage. For perpetual activation, no value to be sent. type: string example: "2016-12-30" overseasCardActivationStartDate: format: date description: Card activation start date in ISO 8601 date format YYYY-MM-DD for overseas usage. For perpetual activation, no value to be sent. type: string example: "2016-11-01" perpetualActivationIndicator: description: Indicator to specify whether the card to be activated perpetually type: string example: "Y" SupplementaryCardResponse: properties: applicationId: description: Unique identifier for the supplementary card application type: string example: ZOW9IO793854 required: - applicationId CreditLimitIncreaseResponse: properties: responseCode: description: Response code.This is a reference data field. Please use /v1/apac/utilities/referenceData/{responseCode} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. type: string example: aeiou SupplementaryCardRequest: properties: applicants: type: array items: $ref: '#/definitions/Applicant' required: - applicants PartnerCustomerDetails: properties: partnerCustomerInternalId: description: Unique customer internal number associated with the partner. type: string example: ZOW9IO793855 partnerCustomerSegment: description: Partner customer segment.This is a reference data field. Please use /v1/apac/utilities/referenceData/{partnerCustomerSegment} resource to get possible value of this field with description. type: string example: AD1 partnerCustomerId: description: Unique customer Id associated with the partner type: string example: P011100000125 ReportLostStolenCardResponse: properties: referenceId: description: Unique reference ID associated with the lost or stolen card request. type: string example: "123456" CardFunctionsAllowed: properties: cardFunction: description: Card function. This is a reference data field. Please use /v1/apac/utilities/referenceData/{cardFunction} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. type: string example: CREDIT_LIMIT_INCREASE TemporaryCreditLimitIncrease: properties: cardId: description: The card identifier in encrypted format. type: string example: 3255613852316f2b4d4d796c344e38756339654972776f663745446e6d4c32486f455a4165374a476858343d creditLimitIncreaseEndDate: format: date description: Credit limit increase end date in ISO 8601 date format YYYY-MM-DD. type: string example: "2016-12-31" reasonCode: description: Reason for the credit limit increase.This is a reference data field. Please use /v1/apac/utilities/referenceData/{reasonCode} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. type: string example: MEDICAL creditLimitIncreaseStartDate: format: date description: Credit limit increase start date in ISO 8601 date format YYYY-MM-DD. type: string example: "2016-12-10" requestedCreditLimitAmount: format: double description: Customer�€�s desired credit limit. This is the combined limit shared with all the existing credit cards of the customer type: number example: 10000.250000 required: - cardId - requestedCreditLimitAmount - creditLimitIncreaseStartDate - creditLimitIncreaseEndDate - reasonCode ErrorResponse: properties: 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 type: description: Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again type: string enum: - error - warn - invalid - fatal moreInfo: description: URI to human readable documentation of the error type: object required: - type - code ReportLostStolenCardRequest: properties: replacementIndicator: description: Indicator to specify whether customer requires card replacement.This is a reference data field. Please use /v1/apac/utilities/referenceData/{replacementIndicator} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. type: string example: BLOCK ONLY CardListingResponse: properties: cardDetails: type: array items: $ref: '#/definitions/CardDetails' Applicant: properties: address: type: array items: $ref: '#/definitions/Address' partnerCustomerDetails: $ref: '#/definitions/PartnerCustomerDetails' motherMaidenName: description: Mother's maiden name type: string example: Monica identificationDocumentDetails: type: array items: $ref: '#/definitions/IdentificationDocumentDetails' phone: type: array minimum: 1 items: $ref: '#/definitions/Phone' employmentDetails: $ref: '#/definitions/EmploymentDetails' name: $ref: '#/definitions/Name' consentDetails: type: array items: $ref: '#/definitions/ConsentDetails' rewardRedemptionAllowedFlag: description: 'Flag to indicated whether reward redemption allowed for supplementary. Valid values: true and false' type: boolean example: false demographics: $ref: '#/definitions/Demographics' required: - motherMaidenName - name - address - phone - employmentDetails - consentDetails securityDefinitions: API Key: type: apiKey name: X-IBM-Client-Id in: header description: "" paths: /v1/cards/{cardId}/activations/{cardActivationCode}: put: description: Activates or deactivates the specified card's ability to be used locally. tags: [] summary: Update local usage activation parameters: - description: Card Id in encrypted format name: cardId type: string required: true in: path - description: Activation Code for card Usage. Possible values:ACTIVATE, DEACTIVATE.This is a reference data field. Please use /v1/apac/utilities/referenceData/{cardActivationCode} resource to get valid value of this field with description. You can use the cardActivationCode as the referenceCode parameter to retrieve the values. name: cardActivationCode type: string required: true in: path - schema: $ref: '#/definitions/CardUsageRequest' description: "" name: CardUsageRequest in: body - name: uuid type: string required: true in: header description: 128 bit random UUID generated uniquely for every request. - name: client_id type: string required: true in: header description: Client ID generated during application registration. - name: Authorization type: string required: true in: header description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' responses: 200: description: Successful operation. 400: schema: $ref: '#/definitions/ErrorResponse' description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
errorinvalidActivationRequestCard is already activated.Selected card must be inactive
errorinvalidDeActivationRequestCard is already de-activated.Selected card must be active
errormaximumAttemptsLimitExceededMaximum attempt limit exceeded
errordecryptionFailedPIN decryption is failed
401: schema: $ref: '#/definitions/ErrorResponse' description:
errorunAuthorizedAuthorization credentials are missing or invalid
403: schema: $ref: '#/definitions/ErrorResponse' description:
erroraccessNotConfiguredAccess is not configured for this resource
500: schema: $ref: '#/definitions/ErrorResponse' description:
fatalserverUnavailableThe request failed due to an internal error
/v1/cards/{cardId}/lostStolen: put: description: Reports a specified card as lost or stolen and returns a reference number to track the request. tags: [] summary: Report card as lost or stolen parameters: - description: 128 bit random UUID generated uniquely for every request. name: uuid required: true type: string in: header - description: Content-Type that are acceptable for the response. name: Accept required: true type: string in: header - description: Client ID generated during application registration. name: client_id required: true type: string in: header - description: application/json name: Content-Type required: true type: string in: header - description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' name: Authorization required: true type: string in: header - description: Unique Id of the card in encrypted format name: cardId required: true type: string in: path - schema: $ref: '#/definitions/ReportLostStolenCardRequest' name: ReportLostStolenCardRequest required: true in: body description: "" responses: 200: schema: $ref: '#/definitions/ReportLostStolenCardResponse' description: Successful operation. 400: schema: $ref: '#/definitions/ErrorResponse' description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
errorrequestNotProcessedRequest is not processed.
401: schema: $ref: '#/definitions/ErrorResponse' description:
errorunAuthorizedAuthorization credentials are missing or invalid
403: schema: $ref: '#/definitions/ErrorResponse' description:
erroraccessNotConfiguredAccess is not configured for this resource
500: schema: $ref: '#/definitions/ErrorResponse' description:
fatalserverUnavailableThe request failed due to an internal error
/v1/cards/{cardId}/overseasUsage: put: description: Activates or deactivates a specified card's ability to be used overseas. Cards can be activated for overseas usage permanently or for a set period of time. tags: [] summary: Update overseas usage activation parameters: - description: 128 bit random UUID generated uniquely for every request. name: uuid required: true type: string in: header - description: Content-Type that are acceptable for the response. name: Accept required: true type: string in: header - description: Client ID generated during application registration. name: client_id required: true type: string in: header - description: application/json name: Content-Type required: true type: string in: header - description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' name: Authorization required: true type: string in: header - description: Unique Id of the card for activation or de-activation. name: cardId required: true type: string in: path - schema: $ref: '#/definitions/OverseasCardUsageRequest' name: OverseasCardUsageRequest required: true in: body description: "" responses: 200: description: Successful operation. 400: schema: $ref: '#/definitions/ErrorResponse' description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
errorinvalidDateRangeDate range is invalid
errorinvalidActivationRequestCard is already activated.Selected card must be inactive
errorinvalidDeActivationRequestCard is already de-activated.Selected card must be active
401: schema: $ref: '#/definitions/ErrorResponse' description:
errorunAuthorizedAuthorization credentials are missing or invalid
403: schema: $ref: '#/definitions/ErrorResponse' description:
erroraccessNotConfiguredAccess is not configured for this resource
500: schema: $ref: '#/definitions/ErrorResponse' description:
fatalserverUnavailableThe request failed due to an internal error
/v1/cards: get: description: Returns an array of credit card numbers, credit limits, statuses and types for the customer who authorized your app. tags: [] summary: Retrieve all cards parameters: - description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' name: Authorization type: string required: true in: header - description: client id generated during consumer onboarding name: client_id type: string required: true in: header - description: 128 bit random UUID generated uniquely for every request. name: uuid type: string required: true in: header - description: Content-Type that are acceptable for the response. name: Accept type: string required: true in: header - description: Card function. This is a reference data field. Please use /v1/apac/utilities/referenceData/{cardFunction} resource to get valid value of this field with description. You can use the field name as the referenceCode parameter to retrieve the values. name: cardFunction type: string required: true in: query responses: 200: schema: $ref: '#/definitions/CardListingResponse' description: Successful operation. 400: schema: $ref: '#/definitions/ErrorResponse' description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
401: schema: $ref: '#/definitions/ErrorResponse' description:
errorunAuthorizedAuthorization credentials are missing or invalid
403: schema: $ref: '#/definitions/ErrorResponse' description:
erroraccessNotConfiguredAccess is not configured for this resource
404: schema: $ref: '#/definitions/ErrorResponse' description:
errorresourceNotFoundEmpty resource/resource not found
500: schema: $ref: '#/definitions/ErrorResponse' description:
fatalserverUnavailableThe request failed due to an internal error
/v1/creditCards/creditLimits: post: description: Requests a permanent or temporary credit limit increase. For a temporary credit limit increase, the request must incidate that the type of request is temporary and include Card ID, requested limit and duration. For permanent increases, the Card ID and requested limit are the only required parameters. tags: [] summary: Request credit limit increase parameters: - description: 128 bit random UUID generated uniquely for every request. name: uuid required: true type: string in: header - description: Content-Type that are acceptable for the response. name: Accept required: true type: string in: header - description: Client ID generated during application registration. name: client_id required: true type: string in: header - description: application/json name: Content-Type required: true type: string in: header - description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' name: Authorization required: true type: string in: header - schema: $ref: '#/definitions/CreditLimitIncreaseRequest' name: CreditLimitIncreaseRequest required: true in: body description: "" responses: 200: schema: $ref: '#/definitions/CreditLimitIncreaseResponse' description: Successful operation. 400: schema: $ref: '#/definitions/ErrorResponse' description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
invalidexceedsEligibleCreditLimitEligible creditlimit is exceeded
invalidinvalideDateRangeDate Range Mismatch
invalidexceedsMaximumAllowableDateRangeAllowable date range is exceeded.
401: schema: $ref: '#/definitions/ErrorResponse' description:
errorunAuthorizedAuthorization credentials are missing or invalid
403: schema: $ref: '#/definitions/ErrorResponse' description:
erroraccessNotConfiguredAccess is not configured for this resource
500: schema: $ref: '#/definitions/ErrorResponse' description:
fatalserverUnavailableThe request failed due to an internal error
/v1/creditCards/{cardId}/supplementary/applications: post: description: Requests an authorized Citi Customer to add a Supplementary card to their existing primary card. tags: [] summary: Supplementary Card Application parameters: - schema: $ref: '#/definitions/SupplementaryCardRequest' description: "" name: SupplementaryCardRequest in: body - description: Primary card id in encrypted format. name: cardId required: true type: string in: path - name: Authorization type: string required: true in: header description: 'The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.' - name: uuid type: string required: true in: header description: 128 bit random UUID generated uniquely for every request. - name: client_id type: string required: true in: header description: Client ID generated during application registration. responses: 200: schema: $ref: '#/definitions/SupplementaryCardResponse' description: Successful operation. 400: schema: $ref: '#/definitions/ErrorResponse' description:
TypeCodeDetails
invalidinvalidRequestMissing or invalid Parameters
errorineligibleCardCard not eligible to request supplementary cards
errorinvalidConsentThe value provided for consentGivenFlag is incorrect
errormaximumSupplementaryCardsExceededAllowed maximum number of supplementary cards exceeded
401: schema: $ref: '#/definitions/ErrorResponse' description:
errorunAuthorizedAuthorization credential is missing or invalid
403: schema: $ref: '#/definitions/ErrorResponse' description:
erroraccessNotConfiguredAccess is not configured for this resource
500: schema: $ref: '#/definitions/ErrorResponse' description:
fatalserverUnavailableThe request failed due to an internal error
security: - API Key: [] consumes: - application/json produces: - application/json x-ibm-endpoints: - endpointUrl: https://sandbox.apihub.citi.com/gcb description: Custom Gateway API Endpoint type: - production - development ...