# Get a buyer

Building with an AI agent? Start at https://docs.payme.io/agents.md

- Sandbox: `GET https://sandbox.payme.io/api/buyers/{buyer_guid}`
- Production: `GET https://live.payme.io/api/buyers/{buyer_guid}`

## Credentials

- Header `PayMe-Merchant-Key` (API key)

Returns the saved details of a buyer: name, contact details and the masked card. Send the seller's MPL (`seller_payme_id`) in the `PayMe-Merchant-Key` header. The buyer must belong to that seller (error `605`).

In the path, send a buyer key (`BUYER…`) from [Capture a buyer token](/payments/tokenization/post-capture-buyer-token) or a sale callback, or a token UUID from `POST /tokens`. With a UUID, the response has no `buyer_key`.

The success body is the buyer object only, with no `status_code` or `session`. The card fields `club`, `type`, `organization` and `origin_country` come from the card's BIN and can be empty when PayMe doesn't recognize it.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`400` | `1` | Required parameter is missing | No seller was named. `status_additional_info` is `seller_payme_id`. 
`500` | `251` | Seller was not found | The seller key is unknown. 
`500` | `163` | Account settings problem - please contact Customer Support | The seller is not active. 
`500` | `600` | Buyer not found | No buyer has this ID. `status_additional_info` is the ID you sent. 
`500` | `604` | Buyer inactive | The buyer is inactive. 
`500` | `605` | The buyer was not captured using the provided seller | This seller may not read this buyer.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | The seller's MPL (`seller_payme_id`), for example `MPLDEMO-MPLDEMO-MPLDEMO-1234567`. Not the seller's public key. |
| `buyer_guid` | path | string | yes | A buyer key (`BUYER…`) or a token UUID. With a UUID, the response has no `buyer_key`. |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/buyers/<buyer_guid>' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/buyers/<buyer_guid>", {
  method: "GET",
  headers: {
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/buyers/<buyer_guid>",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/buyers/<buyer_guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — OK (success)

| Field | Type | Description |
| --- | --- | --- |
| `uuid` | string | The buyer's token UUID. |
| `customer` | object | The buyer's details. |
| `customer.name` | string | The buyer's name. |
| `customer.email` | string | The buyer's email address. |
| `customer.phone` | string | The buyer's phone number. |
| `customer.social_id` | string | The buyer's national ID number. |
| `payment` | object | The saved card. |
| `payment.display` | string | The masked card number. |
| `payment.expiry` | string | Card expiry date, `MMYY`. |
| `payment.brand` | string | Card brand, for example `Visa`. |
| `payment.club` | string | Card club, from the BIN. Can be empty. |
| `payment.type` | string | Card type, for example `Credit`, from the BIN. |
| `payment.organization` | string | Card organization, from the BIN. Can be empty. |
| `payment.origin_country` | string | Country that issued the card, ISO 3166-1 alpha-2, from the BIN. |
| `buyer_key` | string | The buyer key. Returned only when the path holds a buyer key. |

```json
{
  "uuid": "6ac45306-1755-45e4-8b74-f6de3ea2239b",
  "customer": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "phone": "0500000001",
    "social_id": "123456782"
  },
  "payment": {
    "display": "411111******1111",
    "expiry": "1228",
    "brand": "Visa",
    "club": "",
    "type": "Credit",
    "organization": "",
    "origin_country": "US"
  },
  "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567"
}
```

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}
```

### 500 — Internal Server Error (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```