# Create a cardholder ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /v1/issuing/cardholders: post: summary: Create a cardholder deprecated: false description: Creates a new Issuing Cardholder object that can be issued cards. tags: - API Reference/Issuing/Cardholders parameters: - name: Accept in: header description: '' required: true example: application/json schema: type: string - name: Content-Type in: header description: '' required: true example: application/json schema: type: string requestBody: content: application/json: schema: type: object x-apifox-refs: 01HHEXWA8EFVXDWNPWT8SENSBR: &ref_4 $ref: '#/components/schemas/The%20Cardholder%20object' x-apifox-overrides: preferred_locales: null requirements: null id: null object: null created: null livemode: null billing: &ref_0 type: object properties: address: type: object properties: city: type: string description: City, district, suburb, town, or village. country: type: string description: Two-letter country code line1: type: string description: Address line 1 line2: type: string description: Address line 2 postal_code: type: string description: ZIP or postal code. state: type: string description: State, county, province, or region. x-apifox-orders: - city - country - line1 - line2 - postal_code - state description: The cardholder’s billing address. required: - city - country - line1 - postal_code x-apifox-ignore-properties: [] x-apifox-orders: - address description: The cardholder’s billing information. required: - address x-apifox-ignore-properties: [] name: &ref_1 type: string description: >- The cardholder’s name. This will be printed on cards issued to them. email: &ref_2 type: string description: The cardholder’s email address. phone_number: &ref_3 type: string description: >- The cardholder’s phone number. This is required for all cardholders who will be creating EU cards. required: - billing - name - email - phone_number x-apifox-orders: - 01HHEXWA8EFVXDWNPWT8SENSBR properties: billing: *ref_0 name: *ref_1 email: *ref_2 phone_number: *ref_3 metadata: type: array items: type: object properties: {} x-apifox-orders: [] x-apifox-ignore-properties: [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. company: type: object properties: tax_id_provided: type: boolean description: Whether the company’s business ID number was provided. description: Additional information about a company cardholder. x-apifox-orders: - tax_id_provided x-apifox-ignore-properties: [] individual: type: object properties: card_issuing: type: object properties: user_terms_acceptance: type: object properties: date: type: integer description: >- The Unix timestamp marking when the cardholder accepted the Authorized User Terms. Required for Celtic Spend Card users. ip: type: string description: >- The IP address from which the cardholder accepted the Authorized User Terms. Required for Celtic Spend Card users. user_agent: type: string description: >- The user agent of the browser from which the cardholder accepted the Authorized User Terms. x-apifox-orders: - date - ip - user_agent x-apifox-ignore-properties: [] x-apifox-orders: - user_terms_acceptance description: >- Information related to the card_issuing program for this cardholder. x-apifox-ignore-properties: [] dob: type: object properties: day: type: integer description: The day of birth, between 1 and 31. month: type: integer description: The month of birth, between 1 and 12. year: type: integer description: The four-digit year of birth. x-apifox-orders: - day - month - year description: The date of birth of this cardholder. x-apifox-ignore-properties: [] first_name: type: string description: >- The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. last_name: type: string description: >- The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. verification: type: object properties: document: type: object properties: back: type: string description: >- The back of a document returned by a file upload with a purpose value of identity_document. front: type: string description: >- The front of a document returned by a file upload with a purpose value of identity_document. x-apifox-orders: - back - front description: >- An identifying document, either a passport or local ID card. x-apifox-ignore-properties: [] x-apifox-orders: - document description: >- An identifying document, either a passport or local ID card. x-apifox-ignore-properties: [] description: Additional information about an individual cardholder. x-apifox-orders: - card_issuing - dob - first_name - last_name - verification x-apifox-ignore-properties: [] spending_controls: type: object properties: spending_limits: type: object properties: amount: type: integer description: >- Maximum amount allowed to spend per interval. This amount is in the card’s currency and in the smallest currency unit. interval: type: string enum: - per_authorization - daily - weekly - monthly - yearly - all_time description: Interval (or event) to which the amount applies. x-apifox-enum: - value: per_authorization name: '' description: Limit applies to each authorization. - value: daily name: '' description: >- Limit applies to a day, starting at midnight UTC. - value: weekly name: '' description: >- Limit applies to a week, starting on Sunday at midnight UTC - value: monthly name: '' description: Limit applies to a month, starting on the 1st. - value: yearly name: '' description: >- Limit applies to a year, starting on January 1st. - value: all_time name: '' description: Limit applies to all transactions. description: >- Limit spending with amount-based rules that apply across this cardholder’s cards. x-apifox-orders: - amount - interval x-apifox-ignore-properties: [] spending_limits_currency: type: string description: Currency of the amounts within spending_limits. description: Rules that control spending across this cardholder’s cards. x-apifox-orders: - spending_limits - spending_limits_currency x-apifox-ignore-properties: [] status: type: string description: >- Specifies whether to permit authorizations on this cardholder’s cards. enum: - active - inactive - blocked x-apifox-enum: - value: active name: '' description: >- Cards attached to this cardholder can approve authorizations. - value: inactive name: '' description: >- Cards attached to this cardholder will decline all authorizations with the cardholder_inactive reason. - value: blocked name: '' description: >- Cards attached to this cardholder will decline all authorizations without an authorization object created. This status is non-reversible. type: type: string description: One of individual or company. enum: - individual - company x-apifox-enum: - value: individual name: '' description: >- The cardholder is a person, and additional information includes first and last name, date of birth. - value: company name: '' description: >- The cardholder is a company or business entity, and additional information includes their tax ID. required: - billing - name - email - phone_number x-apifox-ignore-properties: - billing - name - email - phone_number - metadata - company - individual - spending_controls - status - type responses: '200': description: '' content: application/json: schema: type: object x-apifox-refs: 01HHEXXAC0A2177554ZR71ZEXD: *ref_4 x-apifox-orders: - 01HHEXXAC0A2177554ZR71ZEXD properties: id: type: string description: Unique identifier for the object. object: type: string description: >- Value is "issuing.cardholder". String representing the object’s type. Objects of the same type share the same value. billing: type: object properties: address: type: object properties: city: type: string description: City, district, suburb, town, or village. country: type: string description: Two-letter country code line1: type: string description: Address line 1 line2: type: string description: Address line 2 postal_code: type: string description: ZIP or postal code. state: type: string description: State, county, province, or region. x-apifox-orders: - city - country - line1 - line2 - postal_code - state description: The cardholder’s billing address. x-apifox-ignore-properties: [] x-apifox-orders: - address description: The cardholder’s billing information. x-apifox-ignore-properties: [] name: type: string description: >- The cardholder’s name. This will be printed on cards issued to them. email: type: string description: The cardholder’s email address. phone_number: type: string description: >- The cardholder’s phone number. This is required for all cardholders who will be creating EU cards. metadata: type: array items: type: object properties: {} x-apifox-orders: [] x-apifox-ignore-properties: [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. company: type: object properties: tax_id_provided: type: boolean description: Whether the company’s business ID number was provided. description: Additional information about a company cardholder. x-apifox-orders: - tax_id_provided x-apifox-ignore-properties: [] created: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. individual: type: object properties: card_issuing: type: object properties: user_terms_acceptance: type: object properties: date: type: integer description: >- The Unix timestamp marking when the cardholder accepted the Authorized User Terms. Required for Celtic Spend Card users. ip: type: string description: >- The IP address from which the cardholder accepted the Authorized User Terms. Required for Celtic Spend Card users. user_agent: type: string description: >- The user agent of the browser from which the cardholder accepted the Authorized User Terms. x-apifox-orders: - date - ip - user_agent x-apifox-ignore-properties: [] x-apifox-orders: - user_terms_acceptance description: >- Information related to the card_issuing program for this cardholder. x-apifox-ignore-properties: [] dob: type: object properties: day: type: integer description: The day of birth, between 1 and 31. month: type: integer description: The month of birth, between 1 and 12. year: type: integer description: The four-digit year of birth. x-apifox-orders: - day - month - year description: The date of birth of this cardholder. x-apifox-ignore-properties: [] first_name: type: string description: >- The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. last_name: type: string description: >- The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. verification: type: object properties: document: type: object properties: back: type: string description: >- The back of a document returned by a file upload with a purpose value of identity_document. front: type: string description: >- The front of a document returned by a file upload with a purpose value of identity_document. x-apifox-orders: - back - front description: >- An identifying document, either a passport or local ID card. x-apifox-ignore-properties: [] x-apifox-orders: - document description: >- An identifying document, either a passport or local ID card. x-apifox-ignore-properties: [] description: Additional information about an individual cardholder. x-apifox-orders: - card_issuing - dob - first_name - last_name - verification x-apifox-ignore-properties: [] livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. spending_controls: type: object properties: spending_limits: type: object properties: amount: type: integer description: >- Maximum amount allowed to spend per interval. This amount is in the card’s currency and in the smallest currency unit. interval: type: string enum: - per_authorization - daily - weekly - monthly - yearly - all_time description: Interval (or event) to which the amount applies. x-apifox-enum: - value: per_authorization name: '' description: Limit applies to each authorization. - value: daily name: '' description: >- Limit applies to a day, starting at midnight UTC. - value: weekly name: '' description: >- Limit applies to a week, starting on Sunday at midnight UTC - value: monthly name: '' description: Limit applies to a month, starting on the 1st. - value: yearly name: '' description: >- Limit applies to a year, starting on January 1st. - value: all_time name: '' description: Limit applies to all transactions. description: >- Limit spending with amount-based rules that apply across this cardholder’s cards. x-apifox-orders: - amount - interval x-apifox-ignore-properties: [] spending_limits_currency: type: string description: Currency of the amounts within spending_limits. description: >- Rules that control spending across this cardholder’s cards. x-apifox-orders: - spending_limits - spending_limits_currency x-apifox-ignore-properties: [] status: type: string description: >- Specifies whether to permit authorizations on this cardholder’s cards. enum: - active - inactive - blocked x-apifox-enum: - value: active name: '' description: >- Cards attached to this cardholder can approve authorizations. - value: inactive name: '' description: >- Cards attached to this cardholder will decline all authorizations with the cardholder_inactive reason. - value: blocked name: '' description: >- Cards attached to this cardholder will decline all authorizations without an authorization object created. This status is non-reversible. type: type: string description: One of individual or company. enum: - individual - company x-apifox-enum: - value: individual name: '' description: >- The cardholder is a person, and additional information includes first and last name, date of birth. - value: company name: '' description: >- The cardholder is a company or business entity, and additional information includes their tax ID. x-apifox-ignore-properties: - id - object - billing - name - email - phone_number - metadata - company - created - individual - livemode - spending_controls - status - type headers: {} x-apifox-name: OK security: - basic: [] x-apifox-folder: API Reference/Issuing/Cardholders x-apifox-status: released x-run-in-apifox: https://app.apifox.com/web/project/1296482/apis/api-132887563-run components: schemas: The Cardholder object: type: object properties: id: type: string description: Unique identifier for the object. object: type: string description: >- Value is "issuing.cardholder". String representing the object’s type. Objects of the same type share the same value. billing: type: object properties: address: type: object properties: city: type: string description: City, district, suburb, town, or village. country: type: string description: Two-letter country code line1: type: string description: Address line 1 line2: type: string description: Address line 2 postal_code: type: string description: ZIP or postal code. state: type: string description: State, county, province, or region. x-apifox-orders: - city - country - line1 - line2 - postal_code - state description: The cardholder’s billing address. x-apifox-ignore-properties: [] x-apifox-orders: - address description: The cardholder’s billing information. x-apifox-ignore-properties: [] name: type: string description: The cardholder’s name. This will be printed on cards issued to them. email: type: string description: The cardholder’s email address. phone_number: type: string description: >- The cardholder’s phone number. This is required for all cardholders who will be creating EU cards. metadata: type: array items: type: object properties: {} x-apifox-orders: [] x-apifox-ignore-properties: [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. company: type: object properties: tax_id_provided: type: boolean description: Whether the company’s business ID number was provided. description: Additional information about a company cardholder. x-apifox-orders: - tax_id_provided x-apifox-ignore-properties: [] created: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. individual: type: object properties: card_issuing: type: object properties: user_terms_acceptance: type: object properties: date: type: integer description: >- The Unix timestamp marking when the cardholder accepted the Authorized User Terms. Required for Celtic Spend Card users. ip: type: string description: >- The IP address from which the cardholder accepted the Authorized User Terms. Required for Celtic Spend Card users. user_agent: type: string description: >- The user agent of the browser from which the cardholder accepted the Authorized User Terms. x-apifox-orders: - date - ip - user_agent x-apifox-ignore-properties: [] x-apifox-orders: - user_terms_acceptance description: >- Information related to the card_issuing program for this cardholder. x-apifox-ignore-properties: [] dob: type: object properties: day: type: integer description: The day of birth, between 1 and 31. month: type: integer description: The month of birth, between 1 and 12. year: type: integer description: The four-digit year of birth. x-apifox-orders: - day - month - year description: The date of birth of this cardholder. x-apifox-ignore-properties: [] first_name: type: string description: >- The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. last_name: type: string description: >- The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. verification: type: object properties: document: type: object properties: back: type: string description: >- The back of a document returned by a file upload with a purpose value of identity_document. front: type: string description: >- The front of a document returned by a file upload with a purpose value of identity_document. x-apifox-orders: - back - front description: An identifying document, either a passport or local ID card. x-apifox-ignore-properties: [] x-apifox-orders: - document description: An identifying document, either a passport or local ID card. x-apifox-ignore-properties: [] description: Additional information about an individual cardholder. x-apifox-orders: - card_issuing - dob - first_name - last_name - verification x-apifox-ignore-properties: [] livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. spending_controls: type: object properties: spending_limits: type: object properties: amount: type: integer description: >- Maximum amount allowed to spend per interval. This amount is in the card’s currency and in the smallest currency unit. interval: type: string enum: - per_authorization - daily - weekly - monthly - yearly - all_time description: Interval (or event) to which the amount applies. x-apifox-enum: - value: per_authorization name: '' description: Limit applies to each authorization. - value: daily name: '' description: Limit applies to a day, starting at midnight UTC. - value: weekly name: '' description: >- Limit applies to a week, starting on Sunday at midnight UTC - value: monthly name: '' description: Limit applies to a month, starting on the 1st. - value: yearly name: '' description: Limit applies to a year, starting on January 1st. - value: all_time name: '' description: Limit applies to all transactions. description: >- Limit spending with amount-based rules that apply across this cardholder’s cards. x-apifox-orders: - amount - interval x-apifox-ignore-properties: [] spending_limits_currency: type: string description: Currency of the amounts within spending_limits. description: Rules that control spending across this cardholder’s cards. x-apifox-orders: - spending_limits - spending_limits_currency x-apifox-ignore-properties: [] status: type: string description: >- Specifies whether to permit authorizations on this cardholder’s cards. enum: - active - inactive - blocked x-apifox-enum: - value: active name: '' description: Cards attached to this cardholder can approve authorizations. - value: inactive name: '' description: >- Cards attached to this cardholder will decline all authorizations with the cardholder_inactive reason. - value: blocked name: '' description: >- Cards attached to this cardholder will decline all authorizations without an authorization object created. This status is non-reversible. type: type: string description: One of individual or company. enum: - individual - company x-apifox-enum: - value: individual name: '' description: >- The cardholder is a person, and additional information includes first and last name, date of birth. - value: company name: '' description: >- The cardholder is a company or business entity, and additional information includes their tax ID. preferred_locales: type: string description: >- The cardholder’s preferred locales (languages), ordered by preference. Locales can be de, en, es, fr, or it. This changes the language of the 3D Secure flow and one-time password messages sent to the cardholder. deprecated: true requirements: type: object properties: disabled_reason: type: string description: >- If disabled_reason is present, all cards will decline authorizations with cardholder_verification_required reason. enum: - listed - under_review - rejected.listed - requirements.past_due x-apifox-enum: - value: listed name: '' description: >- Account might be on a prohibited persons or companies list. The past_due field contains information that you need to provide before the cardholder can approve authorizations. - value: under_review name: '' description: >- This cardholder has raised additional review. Wooshpay will make a decision and update the disabled_reason field. - value: rejected.listed name: '' description: >- Cardholder is rejected because they are on a third-party prohibited persons or companies list (such as financial services provider or government). Their status will be blocked. - value: requirements.past_due name: '' description: >- Cardholder has outstanding requirements. The past_due field contains information that you need to provide before the cardholder can activate cards. past_due: type: string description: >- Array of fields that need to be collected in order to verify and re-enable the cardholder. enum: - individual.card_issuing.user_terms_acceptance.ip - individual.card_issuing.user_terms_acceptance.date - individual.first_name - individual.last_name - individual.dob.day - individual.dob.month - individual.dob.year - individual.verification.document - company.tax_id x-apifox-enum: - value: individual.card_issuing.user_terms_acceptance.ip name: '' description: >- The IP address from which the Cardholder accepted their Authorized User Terms. Required for Celtic Spend Card users. - value: individual.card_issuing.user_terms_acceptance.date name: '' description: >- The Unix timestamp marking when the Cardholder accepted their Authorized User Terms. Required for Celtic Spend Card users. - value: individual.first_name name: '' description: The cardholder’s legal first name. - value: individual.last_name name: '' description: The cardholder’s legal last name. - value: individual.dob.day name: '' description: The cardholder’s date of birth’s day. - value: individual.dob.month name: '' description: The cardholder’s date of birth’s month. - value: individual.dob.year name: '' description: The cardholder’s date of birth’s year. - value: individual.verification.document name: '' description: >- The front and back of a government-issued form of identification. - value: company.tax_id name: '' description: The cardholder’s business number (Tax ID). description: Information about verification requirements for the cardholder. x-apifox-orders: - disabled_reason - past_due deprecated: true x-apifox-ignore-properties: [] x-apifox-orders: - id - object - billing - name - email - phone_number - metadata - company - created - individual - livemode - spending_controls - status - type - preferred_locales - requirements x-apifox-ignore-properties: [] x-apifox-folder: '' securitySchemes: basic: type: http scheme: basic servers: - url: https://apitest.wooshpay.com description: 官网测试 security: - basic: [] ```