Impact Withdrawal Settings API

openapi: 3.2.0
info:
  title: Partner Withdrawal Settings API
  version: '16'
  termsOfService: https://impact.com/terms
  description: Withdrawal Settings hold the bank account, PayPal, and payment scheduling information impact.com uses to pay you out.
  contact:
    name: impact.com Developer Support
    url: https://app.impact.com/secure/help/contact-support.ihtml
    email: developer-support@impact.com
servers:
- url: https://api.impact.com
  description: Production server
security:
- basicAuth: []
tags:
- name: Withdrawal Settings
  description: Endpoints for retrieving and updating your bank account, PayPal, and payment scheduling settings.
paths:
  /Mediapartners/{AccountSID}/WithdrawalSettings:
    get:
      operationId: retrieveWithdrawalSettings
      tags:
      - Withdrawal Settings
      summary: Retrieve withdrawal settings
      description: Returns the partner's current withdrawal settings, including bank account and payment scheduling information.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the partner account.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalSettings'
        '404':
          description: No withdrawal settings are configured for this partner account.
      x-codeSamples:
      - lang: Shell
        label: curl
        source: "curl -L \\\n  --url 'https://api.impact.com/Mediapartners/{AccountSID}/WithdrawalSettings' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: application/json'"
    put:
      operationId: updateWithdrawalSettings
      tags:
      - Withdrawal Settings
      summary: Update withdrawal settings
      description: Updates the partner's withdrawal settings. Only the parameters provided in the request body are changed; all others remain unchanged. Call `RequiredFields` first to learn which fields are mandatory for your country and payment method.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the partner account.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WithdrawalSettingsUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    description: Outcome status of the update.
                    example: OK
                  Uri:
                    type: string
                    description: API resource path for the updated withdrawal settings.
                    example: /Mediapartners/<AccountSID>/WithdrawalSettings
      x-codeSamples:
      - lang: Shell
        label: curl
        source: "curl -L \\\n  --request PUT \\\n  --url 'https://api.impact.com/Mediapartners/{AccountSID}/WithdrawalSettings' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Content-Type: application/x-www-form-urlencoded' \\\n  --header 'Accept: application/json'"
  /Mediapartners/{AccountSID}/WithdrawalSettings/RequiredFields:
    get:
      operationId: retrieveRequiredBankingFields
      tags:
      - Withdrawal Settings
      summary: Retrieve required banking fields
      description: Returns which fields are mandatory when configuring withdrawal settings for a given country and (optionally) payment method. Always call this before updating settings for a country you haven't configured before.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the partner account.
      - name: bankCountry
        in: query
        required: true
        description: ISO 3166-1 alpha-2 or alpha-3 country code where the bank account is held.
        schema:
          type: string
        example: US
      - name: paymentMethod
        in: query
        required: false
        description: Filter the response to a single payment method. If omitted, requirements for all supported methods are returned.
        schema:
          type: string
          enum:
          - BANK_TRANSFER
          - PAYPAL
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequiredFieldsResponse'
      x-codeSamples:
      - lang: Shell
        label: curl
        source: "curl -L \\\n  --url 'https://api.impact.com/Mediapartners/{AccountSID}/WithdrawalSettings/RequiredFields?bankCountry=US' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: application/json'"
components:
  schemas:
    WithdrawalSettingsUpdate:
      type: object
      description: Fields you can submit to update withdrawal settings. Any field omitted from the request is left unchanged.
      properties:
        PaymentMethod:
          type: string
          enum:
          - PAYPAL
          - BANK_TRANSFER
          description: How impact.com sends your payouts. Required when changing payout method.
          example: BANK_TRANSFER
        PaypalEmailAddress:
          type: string
          description: Email address of the PayPal account that receives payouts. Required when `PaymentMethod` is `PAYPAL`.
          example: hazel.nutt@example.com
        BeneficiaryAccountName:
          type: string
          description: Full name on the bank account that will receive funds.
          example: Hazel Nutt
        BankCountry:
          type: string
          description: ISO 3166-1 alpha-2 country code where the bank account is held.
          example: US
        BeneficiaryClassification:
          type: string
          enum:
          - BUSINESS
          - INDIVIDUAL
          - CPF
          - CNPJ
          description: Classification of the account holder. `BUSINESS` and `INDIVIDUAL` apply globally; `CPF` and `CNPJ` are Brazilian taxpayer types.
          example: INDIVIDUAL
        ClassificationCode:
          type: string
          description: Additional classification code required by some country/classification combinations (notably Brazil).
          example: ''
        BeneficiaryAlternativeName:
          type: string
          description: Alternative name on the account, where the bank's system requires one.
          example: ''
        BeneficiaryTaxPayerId:
          type: string
          description: Taxpayer identifier of the beneficiary, in the format used by `BankCountry` (e.g., SSN/EIN for US, CPF/CNPJ for Brazil).
          example: 123-45-6789
        BankAccountType:
          type: string
          enum:
          - CHECKING
          - SAVINGS
          - NOT_SET
          description: Type of bank account that will receive funds.
          example: CHECKING
        BankAccountNumber:
          type: string
          description: The bank account number that will receive funds. For SEPA countries this is the IBAN.
          example: 000123456789
        SwiftCode:
          type: string
          description: SWIFT/BIC code identifying the receiving bank. Required for international transfers.
          example: CHASUS33
        RoutingCode:
          type: string
          description: Domestic routing code for the receiving bank (e.g., US ABA routing number, UK sort code).
          example: '021000021'
        VoCode:
          type: string
          description: Country-specific verification code used by some banking jurisdictions.
          example: ''
        AgencyCode:
          type: string
          description: Bank agency identifier used in some Latin American banking systems.
          example: ''
        BankAddress:
          type: string
          description: Street address of the receiving bank branch.
          example: 270 Park Avenue
        BankPostalCode:
          type: string
          description: Postal code of the receiving bank branch.
          example: '10017'
        BankCity:
          type: string
          description: City of the receiving bank branch.
          example: New York
        BankState:
          type: string
          description: State or province of the receiving bank branch.
          example: NY
        BranchCode:
          type: string
          description: Branch identifier code (e.g., transit number, sort code segment, branch number).
          example: '12345'
        BankName:
          type: string
          description: Name of the receiving bank.
          example: JPMorgan Chase Bank
        BranchName:
          type: string
          description: Name of the receiving bank's branch.
          example: Park Avenue Branch
        PaymentSchedulingType:
          type: string
          enum:
          - BALANCE_THRESHOLD
          - FIXED_DAY
          description: Determines whether payouts trigger by balance threshold or on a fixed day of the month.
          example: BALANCE_THRESHOLD
        PaymentThreshold:
          type: string
          description: Minimum balance that triggers a payout when `PaymentSchedulingType` is `BALANCE_THRESHOLD`. Min $20 USD, max $10,000 USD.
          example: '50.00'
        PaymentDay:
          type: string
          description: Day of month payouts are issued when `PaymentSchedulingType` is `FIXED_DAY`. Either `1` or `15`.
          example: '15'
    RequiredFieldsResponse:
      type: object
      properties:
        BankCountry:
          type: string
          description: Country the requirements apply to.
          example: US
        Currency:
          type: string
          description: Three-letter ISO 4217 currency code paid out for accounts in this country.
          example: USD
        PaymentMethods:
          type: object
          description: Required-field listing keyed by payment method (e.g., `PAYPAL`, `BANK_TRANSFER`).
          additionalProperties:
            type: object
            properties:
              RequiredFields:
                type: array
                description: Names of `WithdrawalSettings` fields that must be supplied for this payment method.
                items:
                  type: string
          example:
            PAYPAL:
              RequiredFields:
              - PaypalEmailAddress
            BANK_TRANSFER:
              RequiredFields:
              - BeneficiaryAccountName
              - BankAccountType
              - BankAccountNumber
              - RoutingCode
    WithdrawalSettings:
      type: object
      properties:
        PaymentMethod:
          type: string
          enum:
          - PAYPAL
          - BANK_TRANSFER
          description: How impact.com sends your payouts.
          example: BANK_TRANSFER
        PaypalEmailAddress:
          type: string
          description: Email address of the PayPal account that receives payouts. Required when `PaymentMethod` is `PAYPAL`.
          example: ''
        BankCountry:
          type: string
          description: ISO 3166-1 alpha-2 country code of the country where the bank account is held.
          example: US
        BeneficiaryAccountName:
          type: string
          description: Full name on the bank account that will receive funds.
          example: ''
        BeneficiaryClassification:
          type: string
          enum:
          - BUSINESS
          - INDIVIDUAL
          - CPF
          - CNPJ
          description: Classification of the account holder. `BUSINESS` and `INDIVIDUAL` apply globally; `CPF` and `CNPJ` are Brazilian taxpayer types.
          example: ''
        ClassificationCode:
          type: string
          description: Additional classification code required by some country/classification combinations (notably Brazil).
          example: ''
        BeneficiaryAlternativeName:
          type: string
          description: Alternative name on the account, where the bank's system requires one.
          example: ''
        BeneficiaryTaxPayerId:
          type: string
          description: Taxpayer identifier of the beneficiary, in the format used by `BankCountry` (e.g., SSN/EIN for US, CPF/CNPJ for Brazil).
          example: ''
        BankAccountType:
          type: string
          enum:
          - CHECKING
          - SAVINGS
          - NOT_SET
          description: Type of bank account that will receive funds.
          example: NOT_SET
        BankAccountNumber:
          type: string
          description: The bank account number that will receive funds. For SEPA countries this is the IBAN.
          example: ''
        SwiftCode:
          type: string
          description: SWIFT/BIC code identifying the receiving bank. Required for international transfers.
          example: ''
        RoutingCode:
          type: string
          description: Domestic routing code for the receiving bank (e.g., US ABA routing number, UK sort code).
          example: ''
        VoCode:
          type: string
          description: Country-specific verification code used by some banking jurisdictions.
          example: ''
        AgencyCode:
          type: string
          description: Bank agency identifier used in some Latin American banking systems.
          example: ''
        BankAddress:
          type: string
          description: Street address of the receiving bank branch.
          example: ''
        BankPostalCode:
          type: string
          description: Postal code of the receiving bank branch.
          example: ''
        BankCity:
          type: string
          description: City of the receiving bank branch.
          example: ''
        BankState:
          type: string
          description: State or province of the receiving bank branch.
          example: ''
        BranchCode:
          type: string
          description: Branch identifier code (e.g., transit number, sort code segment, branch number).
          example: ''
        BankName:
          type: string
          description: Name of the receiving bank.
          example: ''
        BranchName:
          type: string
          description: Name of the receiving bank's branch.
          example: ''
        PaymentSchedulingType:
          type: string
          enum:
          - BALANCE_THRESHOLD
          - FIXED_DAY
          description: Determines whether payouts trigger by balance threshold or on a fixed day of the month.
          example: BALANCE_THRESHOLD
        PaymentThreshold:
          type: string
          description: Minimum account balance that triggers a payout when `PaymentSchedulingType` is `BALANCE_THRESHOLD`. Min $20 USD, max $10,000 USD.
          example: '10000.00'
        PaymentDay:
          type: string
          description: Day of the month payouts are issued when `PaymentSchedulingType` is `FIXED_DAY`. Either `1` or `15`. Returns `0` when not applicable.
          example: '0'
        Uri:
          type: string
          description: API resource path for these withdrawal settings.
          example: /Mediapartners/<AccountSID>/WithdrawalSettings
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
x-default-client: cURL