Getnet DocsGetnet Docs

Create a Staged Digital Wallet Operator payment

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

SDWO (Staged Digital Wallet Operator) is a payment framework for digital wallets that act as intermediaries between the cardholder and the final recipient. When it comes to settlement, funds from payments made through wallets are sent to the EC Wallet, which then transfers them to its end merchants. Currently, the model is structured for Visa, Mastercard, Elo, and Amex. Brazil Only.

It is important to distinguish between the SDWO wallet model and Pass-Through Digital Wallets. In this case, the wallet serves only as a substitute for the physical card and does not participate in the transaction. Therefore, QR code transactions generated at Getnet POS terminals or via NFC wallets (Samsung Pay, Google Pay, and Apple Pay) do not follow the SDWO model but rather the Pass-Through Digital Wallets model.

To help Getnet comply with card brand, arrangement, and BACEN (Banco Central do Brasil) rules for identifying SDWO transactions, Getnet customers that qualify as digital wallets must send certain fields, depending on the applicable brand and SDWO use case.

Transaction models

SDWO supports four transaction models:

ModelTypeCard Brandpay_actionDescription
Stored Value (Me2Me)Cash-inMastercard, Visa, Elo, and AmexFTAdds funds to the same wallet or same-ownership account.
Staged Back-to-back (Purchase)Back-to-backMastercard, Visa, Elo, and AmexFPPurchase via wallet with immediate transfer to a sub-merchant.
Peer-to-peer (P2P)Cash-inMastercard, Visa, and AmexPPTransfer between different users/different ownership and same wallet scheme.
Bill Payment ProviderBill PaymentVisa and AmexBPTransfer of funds from a card to an account, to use the wallet to make a bill payment.

Stored Value (Me2Me)

Adds funds to the same wallet or same ownership account.

  • Topping up Wallet Funds using a Card. E.g.: top up wallet balance via card.
  • Transfer to another person’s balance using card.

Required fields

FieldTypeRequiredDescription
soft_descriptorStringYesMastercard, Visa, and Amex: wallet name only; Elo: Wallet name + * + +TRANSFERENCIA (fixed word: TRANSFERENCIA) Maximum 22 characters.
dynamic_mccIntegerYesUse 6540 for Cash-in. For toll roads, consider the MCC 4784.
wallet.typeStringYesAlways 55.
wallet.idStringYesAlways BRL.
wallet.merchant_idStringYes (Visa, Mastercard, Elo)Digital wallet ID registered with the card brand.
wallet.fund_transfer.pay_actionStringYesAlways FT.
wallet.fund_transfer.receiver.account_numberStringYesUse 9999999999999995 or #NA. For road toll wallet transactions, you must provide the user’s unique toll wallet account ID.
wallet.fund_transfer.receiver.account_typeStringYesAlways 00.
wallet.fund_transfer.receiver.first_nameStringYes (Mastercard); optional otherwiseRecipient first name.
wallet.fund_transfer.receiver.middle_nameStringNoRecipient middle name abbreviation.
wallet.fund_transfer.receiver.last_nameStringYes (Mastercard); optional otherwiseRecipient last name.
wallet.fund_transfer.receiver.addr_streetStringNoRecipient street address and number.
wallet.fund_transfer.receiver.addr_cityStringNoRecipient city.
wallet.fund_transfer.receiver.addr_stateStringNoRecipient state.
wallet.fund_transfer.receiver.addr_countryStringYesISO 3166-1 alpha-3 country code. Example: BRA.
wallet.fund_transfer.receiver.addr_postal_codeStringNoRecipient postal code.
wallet.fund_transfer.receiver.nationalityStringNoISO 3166-1 alpha-3 nationality.
wallet.fund_transfer.receiver.phoneStringNoRecipient phone number, including country code.
wallet.fund_transfer.receiver.date_of_birthStringNoRecipient date of birth. Format YYYYMMDD.
wallet.fund_transfer.receiver.id_typeStringYesDocument type. Use 03 for CPF or CNPJ.
wallet.fund_transfer.receiver.id_numStringYesCPF or CNPJ number.

Example

{
  "amount": 1000,
  "currency": "BRL",
  "customer_id": "cust-sender-001",
  "payment": {
    "payment_method": "CREDIT",
    "save_card_data": false,
    "transaction_type": "FULL",
    "number_installments": 1,
    "soft_descriptor": "DigitalWallet",
    "dynamic_mcc": 6540,
    "card": {
      "number_token": "<card_token>",
      "expiration_month": "09",
      "expiration_year": "30",
      "cardholder_name": "John Smith",
      "security_code": "517",
      "brand": "Mastercard"
    },
    "wallet": {
      "type": "55",
      "id": "BRL",
      "merchant_id": "327",
      "fund_transfer": {
        "pay_action": "FT",
        "receiver": {
          "account_number": "9999999999999995",
          "account_type": "00",
          "first_name": "Jane",
          "middle_name": "T",
          "last_name": "Doe",
          "addr_street": "1 Main ST",
          "addr_city": "SAO PAULO",
          "addr_state": "SP",
          "addr_country": "BRA",
          "addr_postal_code": "01408000",
          "nationality": "BRA",
          "phone": "5511977778888",
          "date_of_birth": "19901230",
          "id_type": "03",
          "id_num": "12345678901"
        }
      }
    }
  }
}

Back-to-back (Purchase)

Purchase via wallet with immediate transfer to a sub-merchant.

  • Payment of printed QR Code / wallet owner using card. Ex.: QR Code of the digital wallet printed at the counter and paid by card.
  • Online payment through the logged-in area of ​​the wallet using a card.

Required fields

FieldTypeRequiredDescription
soft_descriptorStringYesWallet name + * + sub-merchant name. Maximum 22 characters.
dynamic_mccIntegerYesMCC for the sub-merchant’s activity.
wallet.typeStringYesAlways 55.
wallet.idStringYesAlways BRL.
wallet.merchant_idStringYes (Visa, Mastercard, Elo)Digital wallet ID registered with the card brand.
wallet.fund_transfer.pay_actionStringYesAlways FP.
sub_merchant.business_nameStringYes (SDWO)Sub-merchant name. Optional in the base API schema, required for this model.
sub_merchant.foreign_typeStringNoOrigin of sub-merchants. F = all international; P = mixed; D = all domestic.
sub_merchant.identification_codeStringYesUnique sub-merchant identifier. Maximum 15 characters for Visa and Mastercard.
sub_merchant.document_typeStringYesSub-merchant legal document type. One of CPF, CNPJ, PASSPORT_BR, DNI, CUIL, CUIT, PASSPORT_AR, RUT, CI, CURP, or RFC.
sub_merchant.document_numberStringYesSub-merchant legal document number, matching document_type. Minimum 5 and maximum 25 characters.
sub_merchant.addressStringYesSub-merchant street address. Maximum 60 characters.
sub_merchant.cityStringYesSub-merchant city. Maximum 40 characters.
sub_merchant.stateStringYesSub-merchant state. Maximum 3 characters.
sub_merchant.postal_codeStringYes (SDWO)Sub-merchant postal code. Optional in the base API schema, required for this model.

Payment facilitators: The sub_merchant block is the same object described in Payment Facilitators. See that guide for the full field reference and the country and card-brand requirements.

Example

{
  "amount": 5000,
  "currency": "BRL",
  "customer_id": "cust-sender-001",
  "payment": {
    "payment_method": "CREDIT",
    "save_card_data": false,
    "transaction_type": "FULL",
    "number_installments": 1,
    "soft_descriptor": "Wallet*StoreXYZ",
    "dynamic_mcc": 5411,
    "card": {
      "number_token": "<card_token>",
      "expiration_month": "09",
      "expiration_year": "30",
      "cardholder_name": "John Smith",
      "security_code": "517",
      "brand": "Mastercard"
    },
    "wallet": {
      "type": "55",
      "id": "BRL",
      "merchant_id": "327",
      "fund_transfer": {
        "pay_action": "FP"
      }
    }
  },
  "sub_merchant": {
    "business_name": "Store XYZ",
    "foreign_type": "D",
    "identification_code": "9058345",
    "document_type": "CNPJ",
    "document_number": "12345678000195",
    "address": "Rua das Flores 200",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310100"
  }
}

Peer-to-peer (P2P)

Deposit into the account, followed by a transfer of funds to another account held by a different account holder within the same wallet scheme.

Required fields

FieldTypeRequiredDescription
soft_descriptorStringYesMastercard, Visa, and Amex: wallet name only; Elo: Wallet name + * + receiver name. Maximum 22 characters.
dynamic_mccIntegerYesUse 6540 for P2P; for Amex, use 6538. For toll roads, consider the MCC 4784.
wallet.typeStringYesAlways 55.
wallet.idStringYesAlways BRL.
wallet.merchant_idStringYes (Visa, Mastercard, Elo)Digital wallet ID registered with the card brand.
wallet.fund_transfer.pay_actionStringYesAlways PP.
wallet.fund_transfer.receiver.account_numberStringYes (Mastercard); optional otherwiseUse 9999999999999995 or #NA. For road toll wallet transactions, you must provide the user’s unique toll wallet account ID.
wallet.fund_transfer.receiver.account_typeStringYesAlways 00.
wallet.fund_transfer.receiver.first_nameStringYes (Mastercard); optional otherwiseRecipient first name.
wallet.fund_transfer.receiver.middle_nameStringNoRecipient middle name abbreviation.
wallet.fund_transfer.receiver.last_nameStringYes (Mastercard); optional otherwiseRecipient last name.
wallet.fund_transfer.receiver.addr_streetStringNoRecipient street address and number.
wallet.fund_transfer.receiver.addr_cityStringNoRecipient city.
wallet.fund_transfer.receiver.addr_stateStringNoRecipient state.
wallet.fund_transfer.receiver.addr_countryStringYesISO 3166-1 alpha-3 country code. Example: BRA.
wallet.fund_transfer.receiver.addr_postal_codeStringNoRecipient postal code.
wallet.fund_transfer.receiver.nationalityStringNoISO 3166-1 alpha-3 nationality.
wallet.fund_transfer.receiver.phoneStringNoRecipient phone number, including country code.
wallet.fund_transfer.receiver.date_of_birthStringNoRecipient date of birth. Format YYYYMMDD.
wallet.fund_transfer.receiver.id_typeStringYesDocument type. Use 03 for CPF or CNPJ.
wallet.fund_transfer.receiver.id_numStringYesRecipient CPF or CNPJ number.

Example

{
  "amount": 2000,
  "currency": "BRL",
  "customer_id": "cust-sender-001",
  "payment": {
    "payment_method": "CREDIT",
    "save_card_data": false,
    "transaction_type": "FULL",
    "number_installments": 1,
    "soft_descriptor": "DigitalWallet",
    "dynamic_mcc": 6540,
    "card": {
      "number_token": "<card_token>",
      "expiration_month": "09",
      "expiration_year": "30",
      "cardholder_name": "John Smith",
      "security_code": "517",
      "brand": "Mastercard"
    },
    "wallet": {
      "type": "55",
      "id": "BRL",
      "merchant_id": "327",
      "fund_transfer": {
        "pay_action": "PP",
        "receiver": {
          "account_number": "0001234567890",
          "account_type": "00",
          "first_name": "Jane",
          "middle_name": "T",
          "last_name": "Doe",
          "addr_street": "1 Main ST",
          "addr_city": "SAO PAULO",
          "addr_state": "SP",
          "addr_country": "BRA",
          "addr_postal_code": "01408000",
          "nationality": "BRA",
          "phone": "5511977778888",
          "date_of_birth": "19901230",
          "id_type": "03",
          "id_num": "12345678901"
        }
      }
    }
  }
}

Bill Payment Provider

Transferring funds from a card to an account in order to use the wallet to pay a bill.

Required fields

FieldTypeRequiredDescription
soft_descriptorStringYesWallet name only. Maximum 22 characters.
dynamic_mccIntegerYesVisa: as listed below; Amex: MCC of the bill beneficiary.
wallet.typeStringYesAlways 55.
wallet.idStringYesAlways BRL.
wallet.merchant_idStringYes (Visa)Digital wallet ID registered with the card brand.
wallet.fund_transfer.pay_actionStringYesAlways BP.
wallet.fund_transfer.receiver.first_nameStringYes (Amex)For a legal entity (company), the full registered company name must be provided. For an individual, provide the name of the person who is the bill issuer (beneficiary).
wallet.fund_transfer.receiver.middle_nameStringNoFor a legal entity (company), the full registered company name must be provided. For an individual, provide the name of the person who is the bill issuer (beneficiary).
wallet.fund_transfer.receiver.last_nameStringYes (Amex)For a legal entity (company), the full registered company name must be provided. For an individual, provide the name of the person who is the bill issuer (beneficiary).
wallet.fund_transfer.receiver.addr_streetStringYes (Amex)Address of the bill issuer (beneficiary).
wallet.fund_transfer.receiver.addr_cityStringYes (Amex)City of the bill issuer (beneficiary).
wallet.fund_transfer.receiver.addr_stateStringYes (Amex)State of the bill issuer (beneficiary).
wallet.fund_transfer.receiver.addr_countryStringYes (Amex)ISO 3166-1 alpha-3 country code. Example: BRA.
wallet.fund_transfer.receiver.id_typeStringYes (Amex)Document type. Use 03 for CPF or CNPJ.
wallet.fund_transfer.receiver.id_numStringYes (Amex)CPF or CNPJ of the bill issuer (beneficiary).

Visa Bill Payment: Visa requires a specific MCC for each bill payment. Set dynamic_mcc to the value that matches the biller’s category from the list below.

MCCDescription
4814Telecommunication Services, including Local and Long-Distance Calls, Credit Card Calls, Calls Through Use of Magnetic-Stripe-Reading Telephones, and Fax Services
4899Cable, Satellite and Other Pay Television / Radio / Streaming Services
4900Utilities – Electric, Gas, Water, and Sanitary
6012Financial Institutions – Merchandise, Services, and Debt Repayment
6051Non-Financial Institutions – Foreign Currency, Liquid and Cryptocurrency Assets (for example: Cryptocurrency), Money Orders (Not Money Transfer), Account Funding (not Stored Value Load), Travelers Cheques, and Debt Repayment
6300Insurance Sales, Underwriting, and Premiums
6513Real Estate Agents and Managers
8011Doctors and Physicians (Not Elsewhere Classified)
8050Nursing, Home Healthcare and Personal Care Facilities
8062Hospitals
8099Medical Services and Health Practitioners (Not Elsewhere Classified)
8111Legal Services and Attorneys
8211Elementary and Secondary Schools
8220Colleges, Universities, Professional Schools, and Junior Colleges
8241Correspondence Schools
8244Business and Secretarial Schools
8249Vocational and Trade Schools
8299Schools and Educational Services (Not Elsewhere Classified)
8351Child Care Services
9311Tax Payments

Example

Amex example

{
  "amount": 1500,
  "currency": "BRL",
  "customer_id": "cust-sender-001",
  "payment": {
    "payment_method": "CREDIT",
    "save_card_data": false,
    "transaction_type": "FULL",
    "number_installments": 1,
    "soft_descriptor": "DigitalWallet",
    "dynamic_mcc": 4900,
    "card": {
      "number_token": "<card_token>",
      "expiration_month": "09",
      "expiration_year": "30",
      "cardholder_name": "John Smith",
      "security_code": "1234",
      "brand": "Amex"
    },
    "wallet": {
      "type": "55",
      "id": "BRL",
      "fund_transfer": {
        "pay_action": "BP",
        "receiver": {
          "first_name": "Jane",
          "last_name": "Doe",
          "addr_street": "1 Main ST",
          "addr_city": "SAO PAULO",
          "addr_state": "SP",
          "addr_country": "BRA",
          "id_type": "03",
          "id_num": "12345678901"
        }
      }
    }
  }
}

Visa example

{
  "amount": 1500,
  "currency": "BRL",
  "customer_id": "cust-sender-001",
  "payment": {
    "payment_method": "CREDIT",
    "save_card_data": false,
    "transaction_type": "FULL",
    "number_installments": 1,
    "soft_descriptor": "DigitalWallet",
    "dynamic_mcc": 6300,
    "card": {
      "number_token": "<card_token>",
      "expiration_month": "09",
      "expiration_year": "30",
      "cardholder_name": "John Smith",
      "security_code": "517",
      "brand": "Visa"
    },
    "wallet": {
      "type": "55",
      "id": "BRL",
      "merchant_id": "327",
      "fund_transfer": {
        "pay_action": "BP"
      }
    }
  }
}

Request fields

wallet object

Set wallet.type to 55 and wallet.id to BRL for all SDWO transactions in Brazil.

BrandFieldTypeMax lengthRequiredDescription
Allwallet.typeString2YesType of wallet. Use 55 for Local Brazil Wallet (SDWO).
Allwallet.idString5YesWallet identifier. Always BRL for SDWO transactions in Brazil.
Visa / Mastercard / Elowallet.merchant_idString12YesDigital Wallet ID registered with the card network.
Amexwallet.merchant_idString12NoNot applicable.

fund_transfer object

BrandFieldTypeRequiredDescription
Allfund_transfer.pay_actionStringYesTransaction type / financing type.
Allfund_transfer.receiverObjectConditionalRequired for Cash-in and Bill Payments Provider.

receiver object

The receiver object identifies the recipient of the transfer.

FieldTypeMax lengthDescription
account_numberString20Account number. Use #NA or 9999999999999995.
account_typeString2Always 00.
first_nameString35Recipient first name.
middle_nameString1Recipient middle name abbreviation.
last_nameString35Recipient last name.
addr_streetString50Street address and number.
addr_cityString25City.
addr_stateString3State.
addr_countryString3ISO 3166-1 alpha-3 country code. Example: BRA.
addr_postal_codeString10Postal code.
nationalityString3ISO 3166-1 alpha-3 nationality.
phoneString20Phone number including country code.
date_of_birthString8Format YYYYMMDD.
id_typeString2Document type. Use 03 for CPF or CNPJ.
id_numString25Document number (CPF or CNPJ).

sub_merchant object

Use this block for Back-to-back (Purchase) transactions. For the full field reference, including the optional acceptor contact fields, see Payment Facilitators.

FieldTypeRequiredDescription
business_nameStringYes (SDWO)Sub-merchant name. Maximum 80 characters.
foreign_typeStringNoOrigin of sub-merchants. F = all international; P = mixed; D = all domestic.
identification_codeStringYesUnique sub-merchant identifier. Maximum 15 characters for Visa and Mastercard.
document_typeStringYesSub-merchant legal document type. One of CPF, CNPJ, PASSPORT_BR, DNI, CUIL, CUIT, PASSPORT_AR, RUT, CI, CURP, or RFC. Brazilian sub-merchants use CPF or CNPJ.
document_numberStringYesSub-merchant legal document number, matching document_type. Minimum 5 and maximum 25 characters.
addressStringYesStreet address. Maximum 60 characters.
cityStringYesCity. Maximum 40 characters.
stateStringYesState. Maximum 3 characters.
postal_codeStringYes (SDWO)Postal code. Maximum 15 characters.

pay_action

ValueUse case
FTFunding Transfer: Me2Me transactions.
FPFunding and Purchase: Back-to-back transactions.
PPPeer-to-Peer: transfer to another user / other ownership.
BPBill Payment Provider.

account_type

ValueDescription
00Other: Always use 00. Currently, the only allowed value
01RTN + Bank Account
02IBAN
03Card Account
04Email
05Phone Number
06Bank Account Number + BIC
07Wallet ID
08Social Network ID

id_type

ValueDescription
00Passport
01National Identification Card
02Driver’s License
03Government-issued. Use for CPF or CNPJ
04Other

dynamic_mcc

The dynamic_mcc field allows the merchant to use a specific Merchant Category Code for each transaction, according to the product being sold, or according to the merchant associated with the sale in the case of sub-acquirers, correctly identifying the business activity to the transaction.

Since this information is used for classification (which influences approval rate) and transaction fee assessment by the card networks, it is extremely important that it is accurate. The MCC is also highly important for fraud prevention controls and the analysis of purchasing behavior. Card brands, arrangements, and BACEN (Banco Central do Brasil) require it to identify Staged Digital Wallet Operator (SDWO) transactions.

AttributeTypeRequiredDescription
dynamic_mccIntegerYesMCC that overrides the merchant’s registered MCC for the transaction.

If an invalid Dynamic MCC is provided, it will be replaced with the MCC registered in the merchant’s profile and used for the transaction authorization request.

soft_descriptor

soft_descriptor is a field in the payment object that appears on the cardholder’s statement. See Soft descriptor for the soft_descriptor format.

Brand-specific rules

wallet.merchant_id format

BrandID typeLength
VisaMVV (Merchant Value Verification)6 characters
MastercardWID (Wallet ID)3 characters
EloWID (Wallet ID)11 characters

In addition to sending these fields, digital wallets that operate with Visa, Mastercard, and Elo must contact these brands to register and generate their identification number (MVV for Visa, and Wallet ID for Mastercard and Elo), and then submit this information in the requested field.

The role of digital wallets that fall under the SDWO arrangement is to send all requested data to Getnet. Missing fields or values, or incorrect formatting, can result in a declined transaction or a penalty from the card brands.

This section contains the specific data required for wallet payments. Submit this data together with the rest of the payment data, as described in Payments - Global API | Portal API Getnet Docs and Payments - Global API | Portal API Getnet Docs.

Next steps