Update Payment Method

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityData": {
    "paymentMethod": {}
  },
  "relationships": [
    {}
  ],
  "metadata": {}
}
'

import requests

url = "http://api.gu1.ai/entities/{id}"

payload = {
    "entityData": { "paymentMethod": {} },
    "relationships": [{}],
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({entityData: {paymentMethod: {}}, relationships: [{}], metadata: {}})
};

fetch('http://api.gu1.ai/entities/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'entityData' => [
        'paymentMethod' => [
                
        ]
    ],
    'relationships' => [
        [
                
        ]
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{id}"

	payload := strings.NewReader("{\n  \"entityData\": {\n    \"paymentMethod\": {}\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("http://api.gu1.ai/entities/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityData\": {\n    \"paymentMethod\": {}\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityData\": {\n    \"paymentMethod\": {}\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "id": "<string>",
  "entityType": "<string>",
  "entityData": {},
  "relationships": [
    {}
  ],
  "metadata": {},
  "updatedAt": "<string>"
}

PATCH

entities

{id}

Update Payment Method

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityData": {
    "paymentMethod": {}
  },
  "relationships": [
    {}
  ],
  "metadata": {}
}
'

import requests

url = "http://api.gu1.ai/entities/{id}"

payload = {
    "entityData": { "paymentMethod": {} },
    "relationships": [{}],
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({entityData: {paymentMethod: {}}, relationships: [{}], metadata: {}})
};

fetch('http://api.gu1.ai/entities/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'entityData' => [
        'paymentMethod' => [
                
        ]
    ],
    'relationships' => [
        [
                
        ]
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{id}"

	payload := strings.NewReader("{\n  \"entityData\": {\n    \"paymentMethod\": {}\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("http://api.gu1.ai/entities/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityData\": {\n    \"paymentMethod\": {}\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityData\": {\n    \"paymentMethod\": {}\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "id": "<string>",
  "entityType": "<string>",
  "entityData": {},
  "relationships": [
    {}
  ],
  "metadata": {},
  "updatedAt": "<string>"
}

Overview

Updates an existing payment method entity. This endpoint allows partial updates - you only need to provide the fields you want to change.

Endpoint

PATCH http://api.gu1.ai/entities/{id}

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

UUID of the payment method entity to update

Request Body

object

Container for payment method data to update

Show properties

object

Partial payment method data to update (only include fields you want to change)

array

Array of relationships to add or update

object

Additional metadata to update

Example Requests

Update Card Expiration Date

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "paymentMethod": {
        "expiryMonth": "06",
        "expiryYear": "2026"
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/payment-method-uuid-123',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        paymentMethod: {
          expiryMonth: '06',
          expiryYear: '2026'
        }
      }
    })
  }
);

const updated = await response.json();
console.log('Updated expiration date');

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'paymentMethod': {
                'expiryMonth': '06',
                'expiryYear': '2026'
            }
        }
    }
)

updated = response.json()
print('Updated expiration date')

Add Fingerprint to Payment Method

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "paymentMethod": {
        "fingerprint": "abc123xyz456"
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/payment-method-uuid-123',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        paymentMethod: {
          fingerprint: 'abc123xyz456'
        }
      }
    })
  }
);

response = requests.patch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'entityData': {
            'paymentMethod': {
                'fingerprint': 'abc123xyz456'
            }
        }
    }
)

Update Holder Name

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "paymentMethod": {
        "holderName": "Jane Smith"
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/payment-method-uuid-123',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        paymentMethod: {
          holderName: 'Jane Smith'
        }
      }
    })
  }
);

response = requests.patch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'entityData': {
            'paymentMethod': {
                'holderName': 'Jane Smith'
            }
        }
    }
)

Add Metadata

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "isDefault": true,
      "addedVia": "mobile_app",
      "verifiedAt": "2024-12-23T10:00:00Z"
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/payment-method-uuid-123',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      metadata: {
        isDefault: true,
        addedVia: 'mobile_app',
        verifiedAt: new Date().toISOString()
      }
    })
  }
);

from datetime import datetime

response = requests.patch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'metadata': {
            'isDefault': True,
            'addedVia': 'mobile_app',
            'verifiedAt': datetime.utcnow().isoformat() + 'Z'
        }
    }
)

Response

boolean

Whether the operation was successful

string

UUID of the updated payment method entity

string

Always "payment_method"

object

The complete updated payment method data

array

Array of relationships

object

Complete metadata after update

string

ISO 8601 timestamp of this update

Response Example

{
  "success": true,
  "id": "payment-method-uuid-123",
  "entityType": "payment_method",
  "entityData": {
    "paymentMethod": {
      "type": "credit_card",
      "last4": "4242",
      "brand": "visa",
      "expiryMonth": "06",
      "expiryYear": "2026",
      "holderName": "John Doe",
      "issuerCountry": "BR",
      "bin": "424242",
      "funding": "credit",
      "fingerprint": "abc123xyz456"
    }
  },
  "relationships": [
    {
      "targetEntityId": "person-uuid-123",
      "relationshipType": "owns",
      "strength": 1.0
    }
  ],
  "metadata": {
    "isDefault": true,
    "addedVia": "mobile_app",
    "verifiedAt": "2024-12-23T10:00:00Z"
  },
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-12-23T10:15:00.000Z"
}

Use Cases

Update Expired Card

async function updateExpiredCard(paymentMethodId, newExpiry) {
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          paymentMethod: {
            expiryMonth: newExpiry.month,
            expiryYear: newExpiry.year
          }
        },
        metadata: {
          updatedReason: 'card_renewal',
          updatedAt: new Date().toISOString()
        }
      })
    }
  );

  return await response.json();
}

// Usage
await updateExpiredCard('payment-method-uuid-123', {
  month: '12',
  year: '2027'
});

Mark as Default Payment Method

async function setDefaultPaymentMethod(personId, paymentMethodId) {
  // First, remove default flag from all other payment methods
  const listResponse = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities } = await listResponse.json();

  // Update all to not default
  await Promise.all(
    entities.map(pm =>
      fetch(`http://api.gu1.ai/entities/${pm.id}`, {
        method: 'PATCH',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          metadata: { isDefault: false }
        })
      })
    )
  );

  // Set new default
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: { isDefault: true }
      })
    }
  );

  return await response.json();
}

Add Verification Status

async function markPaymentMethodVerified(paymentMethodId, verificationData) {
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: {
          verified: true,
          verifiedAt: new Date().toISOString(),
          verificationMethod: verificationData.method,
          verificationId: verificationData.id
        }
      })
    }
  );

  return await response.json();
}

Error Responses

404 Not Found

{
  "error": "Entity not found",
  "entityId": "payment-method-uuid-123"
}

400 Bad Request

{
  "error": "Invalid update data",
  "details": {
    "entityData.paymentMethod.expiryMonth": "Must be between 01 and 12"
  }
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

Important Notes

This is a partial update endpoint - only fields provided will be updated
Other fields will remain unchanged
To remove a field, explicitly set it to null
Updates to sensitive fields (like card numbers) may be restricted

The updatedAt timestamp is automatically set to the current time
Risk scores may be recalculated after updates
Related transactions are not affected by payment method updates

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Example Requests

​Update Card Expiration Date

​Add Fingerprint to Payment Method

​Update Holder Name

​Add Metadata

​Response

​Response Example

​Use Cases

​Update Expired Card

​Mark as Default Payment Method

​Add Verification Status

​Error Responses

​404 Not Found

​400 Bad Request

​401 Unauthorized

​Important Notes

​See Also

Overview

Endpoint

Authentication

Path Parameters

Request Body

Example Requests

Update Card Expiration Date

Add Fingerprint to Payment Method

Update Holder Name

Add Metadata

Response

Response Example

Use Cases

Update Expired Card

Mark as Default Payment Method

Add Verification Status

Error Responses

404 Not Found

400 Bad Request

401 Unauthorized

Important Notes

See Also