Swiped Card

Swiped card payments use magstripe data from a physical card to capture encrypted card details and process an in-person transaction. Instead of typing card data manually, the merchant passes the magstripe data from a supported reader to the payment API.

Prerequisites and limitations

• Prerequisites: A supported magstripe reader (standalone terminal or integrated with a virtual terminal), a configured merchant account, and access to the PCE /payment API.
• Limitations: Swiped payments require the physical card to be present and a compatible reader. If your environment requires EMV or NFC for compliance, you should use those methods instead of swipe.

When to Use Swiped Card Payments

Swiped transactions are suitable when:

• The merchant has the physical card and a swipe/magstripe reader, either as a standalone terminal or integrated with a virtual terminal.
• The card doesn’t have a chip, or the merchant only supports swipe transactions.
• An EMV chip read fails and the terminal falls back to asking the customer to swipe.
• The card is physically present at the point of sale (typical card-present use case).

Required Equipment

You’ll need:

• A supported magstripe reader or terminal, connected to your POS or virtual terminal.
• A PCE-enabled merchant account.

Check the Supported Hardware documentation for a complete list of compatible card readers and terminal models.

Things to Keep in Mind

• Fast customer experience: Swipe is quick and familiar for cardholders.
• Card-present pricing: Processing fees are typically lower than card-not-present, because the card is physically present.
• Hardware dependency: You must integrate with at least one supported card reader, and the merchant needs to purchase and maintain that equipment.
• Fallback behavior: Some terminals automatically fall back to swipe if the EMV chip is unreadable.

Make a Swiped Payment Request

Swiped magstripe data is sent in the cardAccount.magstripe field on the /payment endpoint.

Endpoint

Steps

1. Set up the HTTP request

   • Use the POST method.
   • Call the /payment endpoint in the appropriate environment (sandbox or production).

2. Add authentication and headers

   • Send your username and password in the Authorization header using Basic auth.

     • Encode username:password with Base-64 and prefix with Basic .

   • Set the Content-Type header to application/json.

3. Provide the magstripe data in the request body

   Build a JSON payload similar to the following, using the magstripe field inside cardAccount:

{
   "merchantId" :"4xxx0",
   "tenderType" :"Card",
   "amount" :"0.01",
   "cardAccount" :{
       "magstripe":"%B40xxxxxxxx02060^YOU/A GIFT
       FOR^23xxxxx00000000000?;4077140007002060=230xxxxxx000000000000000?
       |0600|CBD4049DD42DA0Axxxxxxxx6A3B293572F568CEFBB7554E09D11D25499DB9
       xxxxxxxxxxxxxAD74742C569BFDB|F7E12F8E98E49574E3A
       xxxxxxxxxxxxxC3CC5F85F904ED6CD9C12||61402200|AF530884B3
       xxxxxxxxxx29AA610CD460573A2F1F11EE80C9665CB94826E
       xxxxxxxxxxx668B2E613AE30A8C7A961680071771986B5F|B23011
       xxxx313AA|AB4F2xxxxB05C9|9013250xxxx11500011B|385D||0000"
       }
  }

• merchantId: Your merchant identifier.
• tenderType: Set to "Card" for card transactions.
• amount: The transaction amount.
• cardAccount.magstripe: The full magstripe string captured from the card reader (example truncated here).

4. (Optional) Return the full response with echo

• If you want the full payment object in the response, add echo=true as a URL parameter: POST /payment?echo=true
• This avoids making an additional GET call to retrieve the payment details.

5. Test with a card number

• In Sandbox, you can use any test credit card number in a valid card format.
• If you pass magstripe data from a real test card, it will not be charged in Sandbox because the environment uses a simulator instead of a real payment gateway.

6. Verify the response

• A successful request returns HTTP 201 Created.
• The payment object’s status field should be set to Approved if the transaction is approved.
• To generate Declined responses in Sandbox, use the documented testing card numbers or scenarios for negative testing.

Testing Behavior in Sandbox

• Sandbox approves all valid card formats by default.

• Use special test card numbers or configurations (for example, specific amounts or card patterns) to simulate:

  • Declines
  • AVS/CVV failures
  • Other error states

Check the testing cards reference for the exact values and expected outcomes.